feat: AES-256-GCM column-level encryption for user PII

[AndresL230]

Summary

Adds AES-256-GCM column-level encryption for user PII, OAuth tokens, assignment notes/points, document summaries/concept notes, session summaries, and chat messages. Includes encrypt-on-write + decrypt-on-read across all affected routes, a schema migration that retypes encrypted columns to TEXT, and an idempotent backfill script for existing rows.

Rollout — three things you need to do

1. What to apply to Supabase

Run one SQL file in the Supabase SQL editor: backend/db/migration_encryption_text_columns.sql. It contains four ALTER TABLE ... ALTER COLUMN ... TYPE TEXT USING ::TEXT statements.

Apply it once, before deploying the new code. The casts preserve existing rows as TEXT (e.g., 87.5 becomes the string "87.5"); the decrypt_if_present / decrypt_numeric fallbacks keep those legacy rows readable until you backfill.

2. Values you need to set

Just one new env var. ENCRYPTION_KEY = 64 hex chars (32 bytes). Generate it with:

python -c "import secrets; print(secrets.token_hex(32))"

Set it in:

• backend/.env for local dev (backend/.env.example already has the placeholder + the generation command).
• Wherever your backend actually runs in deploy (Cloudflare Workers/Pages env vars, Vercel, Fly, Railway, whatever — the same place SUPABASE_SERVICE_KEY is set today). docker-compose.yml already passes it through from backend/.env.

Two non-negotiables:

• The same key must be used everywhere your backend runs. Different keys = ciphertext written by one instance is unreadable by another.
• Never rotate or lose this key. Losing it permanently bricks every encrypted column. If you need to rotate, write a script that decrypts with the old key and re-encrypts with the new one in one transaction.

The backend will refuse to boot if ENCRYPTION_KEY is missing, not 64 chars, or not valid hex (intentional fail-fast).

3. The backfill script

backend/db/backfill_encryption.py. For each encrypted column on each table (users.name/email/bio/..., oauth_tokens.access_token/refresh_token, assignments.notes/points_*, documents.summary/concept_notes, sessions.summary_json, messages.content, room_messages.text), it:

1. Selects every row.
2. For each cell, calls decrypt(value) once.
3. If it succeeds → already encrypted → skip.
4. If it raises → the cell is still legacy plaintext → encrypt it and write back.

Prints counts per column. Idempotent — running it a second time changes nothing. Defaults to dry-run (counts only); --apply to actually write. --table users to do it in stages.

How to actually run all of this, in order

# 1. Generate and set the key
python -c "import secrets; print(secrets.token_hex(32))"# paste output as ENCRYPTION_KEY=... in backend/.env# AND set the same value in your deploy environment# 2. Apply the schema migration in Supabase# Dashboard → SQL Editor → paste contents of:# backend/db/migration_encryption_text_columns.sql → Run# 3. Deploy the new backend code (encryption wiring is on this branch)# 4. Backfill — first dry-run to see what will change:cd backend
.\venv\Scripts\python.exe -m db.backfill_encryption
# 5. Then actually apply:
.\venv\Scripts\python.exe -m db.backfill_encryption --apply

After the backfill completes successfully, the decrypt_if_present fallback-to-raw-value warnings should stop appearing in logs. That's the signal it worked.

Test plan

• Apply migration_encryption_text_columns.sql to a Supabase branch DB
• Set ENCRYPTION_KEY (64-hex) and confirm backend boots; confirm it refuses to boot when the var is missing/invalid
• Run backend tests: cd backend && python -m pytest tests/ -q (includes new test_encryption.py)
• Sign in via Google OAuth → confirm users.name/email written as ciphertext, /me returns plaintext
• Upload a document → confirm documents.summary/concept_notes ciphertext at rest, decrypt on library/study-guide/flashcards reads
• Sync calendar → confirm oauth_tokens.access_token/refresh_token and assignments.notes/points_* encrypted
• Send a room message + a learn-session message → confirm room_messages.text and messages.content encrypted
• Run backfill in dry-run on a copy of prod data, verify counts, then --apply and re-run to confirm idempotency (zero changes)
• Confirm decrypt_if_present fallback warnings disappear from logs after backfill

Summary by CodeRabbit

• New Features

  • End-to-end encryption for sensitive data (profiles, documents, sessions, messages, tokens).

• Improvements

  • Decryption in responses and encryption on save for many user-facing flows.
  • Tighter per-request authorization across endpoints and stricter ownership checks.

• Chores

  • Added encryption key configuration and dependency updates; adjusted schema to support encrypted values.

• Tests & Docs

  • Added encryption test coverage and an implementation/rollout plan.

[cloudflare-workers-and-pages]

Deploying with Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Preview URL	Updated (UTC)
✅ Deployment successful! View logs	frontend	43d9015	Commit Preview URL Branch Preview URL	May 03 2026, 07:57 PM

[coderabbitai]

📝 Walkthrough

Walkthrough

Adds AES-256-GCM column-level encryption: new encryption service, test coverage, env/docker wiring, a migration to TEXT for certain columns, a one-shot backfill CLI, and pervasive route changes to encrypt sensitive writes, decrypt reads, and enforce request-based authorization.

Changes

Encryption rollout & route wiring

Layer / File(s)	Summary
Data Shape / Schema Prep backend/db/migration_encryption_text_columns.sql	Retypes specific numeric/JSONB columns to TEXT using USING <col>::TEXT to allow storing ciphertext strings.
Dependencies backend/requirements.txt	Pins cryptography (>=42,<46).
Environment backend/.env.example, docker-compose.yml	Adds ENCRYPTION_KEY placeholder and passes ${ENCRYPTION_KEY} into the backend service.
Encryption Core backend/services/encryption.py	New AES-256-GCM helpers: key loader/validation, encrypt/decrypt, encrypt_if_present/decrypt_if_present, decrypt_numeric, encrypt_json/decrypt_json.
Backfill Tool backend/db/backfill_encryption.py	One-shot CLI that scans configured tables/columns, detects already-encrypted vs legacy plaintext/JSON/numeric values, and optionally writes encrypted values with --apply.
Auth Guard Tightening backend/services/auth_guard.py	get_session_user_id now requires a valid session token (no query-param fallback) and raises 401 on missing/invalid payload.
Route Integration (reads/writes & auth) backend/routes/*.py (auth, onboarding, profile, admin, social, quiz, learn, calendar, gradebook, documents, flashcards, study_guide, graph)	Handlers now accept Request where applicable, enforce require_self/session ownership, encrypt sensitive fields on write and decrypt on read, and narrow SELECT projections. OAuth tokens are decrypted for use and encrypted on refresh/storage. Several patch/allowlist behaviors adjusted to exclude sensitive fields.
Frontend adjustments frontend/src/app/auth/callback/page.tsx, frontend/src/app/api/auth/session/route.ts, frontend/src/middleware.ts	Auth callback no longer requires name param and fetches /api/auth/me from session; session route now requires/verifies authToken; middleware forwards sapling_session cookie to backend auth check.
Tests & Test Setup backend/tests/conftest.py, backend/tests/test_encryption.py, backend/tests/*	Deterministic test key in env, autouse fixture bypasses session auth for route tests, new encryption unit tests (string/JSON/numeric/nonce/tamper), and multiple route test updates to accommodate request-based auth and encrypted fields.
Docs / Plan docs/superpowers/plans/2026-05-03-aes-256-gcm-column-encryption.md	Comprehensive rollout plan, inventory of # ENCRYPTED LATER markers, migration/backfill instructions, and follow-up tasks.

Sequence Diagram

sequenceDiagram
participant Client
participant RouteHandler
participant AuthGuard
participant EncryptionSvc
participant Database
rect rgba(100, 150, 200, 0.5)
Note over Client,Database: Write path (encrypt before persist)
Client->>RouteHandler: POST /api/... (user_id, sensitive)
RouteHandler->>AuthGuard: require_self(user_id, request)
AuthGuard-->>RouteHandler: authorized
RouteHandler->>EncryptionSvc: encrypt(sensitive)
EncryptionSvc-->>RouteHandler: ciphertext
RouteHandler->>Database: INSERT/UPDATE (ciphertext)
Database-->>RouteHandler: OK
RouteHandler-->>Client: 200 (response with decrypted fields)
end
rect rgba(150, 200, 100, 0.5)
Note over Client,Database: Read path (decrypt on load)
Client->>RouteHandler: GET /api/.../{user_id}
RouteHandler->>AuthGuard: require_self(user_id, request)
AuthGuard-->>RouteHandler: authorized
RouteHandler->>Database: SELECT (ciphertext_field)
Database-->>RouteHandler: row with ciphertext
RouteHandler->>EncryptionSvc: decrypt_if_present(ciphertext)
EncryptionSvc-->>RouteHandler: plaintext or legacy value
RouteHandler-->>Client: 200 (plaintext)
end
rect rgba(200, 100, 100, 0.5)
Note over RouteHandler,EncryptionSvc: Legacy plaintext fallback
RouteHandler->>EncryptionSvc: decrypt_if_present(legacy_plaintext)
EncryptionSvc-->>RouteHandler: returns original plaintext (logs warning)
end

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Possibly related PRs

• adding approval gate for closed beta #56: Overlaps changes to backend/routes/auth.py GET /me (authorization and returned fields).
• Course ID schema migration + calendar assignment normalization #53: Overlaps calendar assignment flows and OAuth token handling in backend/routes/calendar.py.
• Frontend revamp (M1-M9 + deferred items + production hardening) #62: Related frontend session handling changes to frontend/src/app/api/auth/session/route.ts (cookie/session verification).

Poem

🐰
I hopped through code at dawn's first light,
Wrapped secrets snug in AES so tight,
Nonces fresh, each byte takes flight,
Now data sleeps secure each night.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 16.56% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'feat: AES-256-GCM column-level encryption for user PII' directly and clearly summarizes the main feature being added—column-level encryption for sensitive user data.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description check	✅ Passed	The PR description comprehensively covers what the PR does, why, rollout steps, environment configuration, backfill instructions, and test plan—all aligned with the description template structure.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/aes-256-gcm-encryption

Tip

💬 Introducing Slack Agent: The best way for teams to turn conversations into code.

Slack Agent is built on CodeRabbit's deep understanding of your code, so your team can collaborate across the entire SDLC without losing context.

• Generate code and open pull requests
• Plan features and break down work
• Investigate incidents and troubleshoot customer tickets together
• Automate recurring tasks and respond to alerts with triggers
• Summarize progress and report instantly

Built for teams:

• Shared memory across your entire org—no repeating context
• Per-thread sandboxes to safely plan and execute work
• Governance built-in—scoped access, auditability, and budget controls

One agent for your entire SDLC. Right inside Slack.

👉 Get started

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 4

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (4)

backend/routes/quiz.py (1)

190-203: ⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Guard student_name against nulls before template replacement.

decrypt_if_present() can return None. If users.name is null, the .replace("{student_name}", student_name) call raises TypeError after the quiz attempt and mastery updates have already been persisted.

Suggested fix

- student_name = decrypt_if_present(user_rows[0]["name"]) if user_rows else "Student"+ student_name = (+ decrypt_if_present(user_rows[0].get("name")) or "Student"+ if user_rows+ else "Student"+ )

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.
In `@backend/routes/quiz.py` around lines 190 - 203, The student_name value used
in the prompt can be None because decrypt_if_present(user_rows[0]["name"]) may
return None; before calling .replace("{student_name}", student_name) ensure
student_name is a non-null string (e.g., coerce to a fallback like "Student" or
"" if None) so template replacement never receives None; update the code around
where student_name is assigned (the decrypt_if_present call and subsequent use
in ctx_prompt/_load_prompt) to coerce or default the value and use that
sanitized variable in the .replace call.

backend/routes/gradebook.py (1)

242-255: ⚠️ Potential issue | 🟠 Major | ⚡ Quick win

Return decrypted fields from create_assignment().

This route now writes encrypted points_possible, points_earned, and notes, then returns inserted[0] verbatim. Any client that uses the POST response to update local state will receive ciphertext instead of the values it just submitted, while the read endpoints return plaintext.

Suggested fix

 inserted = table("assignments").insert({
"id": new_id,
"user_id": body.user_id,
"course_id": body.course_id,
"title": body.title,
"category_id": body.category_id,
"points_possible": encrypt_if_present(body.points_possible),
"points_earned": encrypt_if_present(body.points_earned),
"due_date": body.due_date,
"assignment_type": body.assignment_type,
"notes": encrypt_if_present(body.notes),
"source": "manual",
})
- return {"assignment": inserted[0] if inserted else None}+ assignment = inserted[0] if inserted else None+ if assignment:+ assignment["points_possible"] = decrypt_numeric(assignment.get("points_possible"))+ assignment["points_earned"] = decrypt_numeric(assignment.get("points_earned"))+ assignment["notes"] = decrypt_if_present(assignment.get("notes"))+ return {"assignment": assignment}

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.
In `@backend/routes/gradebook.py` around lines 242 - 255, The POST handler
currently inserts encrypted values (using encrypt_if_present) and returns
inserted[0] as-is, causing ciphertext to be returned; after the insert in
create_assignment (the block that builds inserted =
table("assignments").insert(...)), decrypt the stored fields before returning by
running points_possible, points_earned, and notes through the corresponding
decrypt helper (e.g., decrypt_if_present) and then return the modified
assignment object (rather than the raw inserted[0]); update the return to return
{"assignment": decrypted_assignment} so clients receive plaintext fields
consistent with read endpoints.

backend/routes/learn.py (1)

525-532: ⚠️ Potential issue | 🟠 Major | ⚡ Quick win

Messages returned by resume_session are not decrypted.

When resuming a persisted session, the messages fetched from the database have encrypted content but are returned directly without decryption. This is inconsistent with get_conversation_history which decrypts message content.

🐛 Proposed fix

 msgs = table("messages").select(
"id,role,content,created_at",
filters={"session_id": f"eq.{session_id}"},
order="created_at.asc",
)
+ for m in msgs:+ m["content"] = decrypt_if_present(m.get("content"))
return {
"session": session_rows[0],
"messages": msgs,
}

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.
In `@backend/routes/learn.py` around lines 525 - 532, The messages returned by
resume_session are fetched into msgs via table("messages").select but not
decrypted; update resume_session to reuse the decryption logic from
get_conversation_history (or call get_conversation_history(session_id) instead
of returning raw msgs) so each message's content is decrypted before returning.
Locate the msgs variable and the return that currently returns session_rows[0]
and msgs, then either map over msgs and replace each message's content with the
decrypted value using the same helper used by get_conversation_history, or
delegate to get_conversation_history to produce the decrypted messages, and
return that result.

backend/routes/social.py (1)

343-371: ⚠️ Potential issue | 🟠 Major

user_name is stored unencrypted in room_messages.

The message text is encrypted but body.user_name is stored in plaintext. This is inconsistent with the PR's goal of encrypting PII. User names are PII and should be encrypted at rest.

This also requires updating get_room_messages to decrypt user_name in the message rows (line 290) and reply snippets (line 320).

🔒 Proposed fix to encrypt user_name

 row = table("room_messages").insert({
"room_id": room_id,
"user_id": body.user_id,
- "user_name": body.user_name,+ "user_name": encrypt_if_present(body.user_name),
"text": encrypt_if_present(body.text or None),
"image_url": body.image_url or None,
"reply_to_id": body.reply_to_id or None,
})
if row:
row[0]["text"] = decrypt_if_present(row[0].get("text"))
+ row[0]["user_name"] = decrypt_if_present(row[0].get("user_name"))

In get_room_messages, decrypt user_name when retrieving message rows and reply snippets.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.
In `@backend/routes/social.py` around lines 343 - 371, send_room_message currently
stores body.user_name in plaintext; update the insert in send_room_message to
pass user_name through encrypt_if_present (same pattern as text) so user_name is
encrypted at rest. Then update get_room_messages to call decrypt_if_present on
the message row's user_name and also on any reply snippet user_name (the
reply_to handling at/around where reply snippets are built) to return decrypted
names to clients; preserve null/None handling consistent with
encrypt_if_present/decrypt_if_present usage.

🧹 Nitpick comments (8)

backend/services/auth_guard.py (1)

60-61: 💤 Low value

Add exception chaining for better error tracing.

While catching a broad Exception is acceptable here (any decode failure should yield 401), using raise ... from would preserve the original exception context for debugging.

♻️ Suggested improvement

- except Exception:- raise HTTPException(status_code=401, detail="Not authenticated")+ except Exception as exc:+ raise HTTPException(status_code=401, detail="Not authenticated") from exc

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.
In `@backend/services/auth_guard.py` around lines 60 - 61, The except block
currently swallows the original exception; update the handler in auth_guard.py
so the broad except Exception captures the original exception (e.g., except
Exception as e:) and re-raise the HTTPException with exception chaining (raise
HTTPException(status_code=401, detail="Not authenticated") from e) to preserve
the original traceback for debugging while still returning 401 from the
authentication function/handler.

backend/routes/onboarding.py (1)

14-14: 💤 Low value

Unused request parameter in search_courses.

The request: Request parameter is accepted but never used in this function. If this is intentional for consistency or future auth guards, consider adding a comment. Otherwise, remove it to avoid confusion.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.
In `@backend/routes/onboarding.py` at line 14, The function search_courses
currently declares an unused parameter request: Request which causes confusion;
either remove the request parameter from the function signature of
search_courses (and any corresponding route decorator/handler registration) or,
if it's intentionally reserved for future use (e.g., auth or middleware), add an
inline comment above the signature explaining why request is unused (e.g., "#
request kept for future auth guard") and prefix the variable with an underscore
(request -> _request) to signal intentional non-use. Update any callers or route
mappings that expect the old signature accordingly and ensure imports (Request)
are cleaned up if removed.

backend/db/backfill_encryption.py (2)

91-91: 🏗️ Heavy lift

No pagination — large tables may cause memory/timeout issues.

table(table_name).select(...) on line 91 (and similar calls) loads all rows into memory. For tables with millions of rows (e.g., messages, room_messages), this could exhaust memory or timeout.

Consider adding batching with limit and offset, or using cursor-based pagination:

Example batch approach

BATCH_SIZE=1000offset=0whileTrue:
rows=table(table_name).select(
",".join([pk, *columns]),
limit=BATCH_SIZE,
offset=offset,
order=f"{pk}.asc"
) or []
ifnotrows:
break# process rows...offset+=BATCH_SIZE

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.
In `@backend/db/backfill_encryption.py` at line 91, The current call rows =
table(table_name).select(",".join([pk, *columns])) loads the entire table into
memory; change the logic around table(table_name).select to iterate in batches
(use limit/offset or a cursor) while selecting the same columns (referencing
table_name, pk, columns and the table(...) call) so you fetch e.g. BATCH_SIZE
rows at a time, process them, then advance the offset (or cursor) and repeat
until no rows remain; ensure you preserve ordering (order by pk) to make
pagination deterministic and avoid loading all rows into memory.

---

162-172: 💤 Low value

Corrupt JSON encrypted as raw string may cause decrypt mismatch.

When JSON parsing fails (line 164), the raw string is encrypted via encrypt(v) (line 169). However, reads use decrypt_json() which expects json.loads(decrypt(value)). Decrypting will succeed, but json.loads will fail on the corrupt JSON, triggering the fallback path.

This is acceptable since the fallback handles it, but documenting this behavior would help future maintainers understand why some cells fail JSON parsing after decryption.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.
In `@backend/db/backfill_encryption.py` around lines 162 - 172, When JSON parsing
fails in backfill_encryption.py (the _json.loads(v) exception path), we
currently encrypt the raw string with encrypt(v) so the value can round-trip
through decrypt_if_present/decrypt_json(); add a clear inline comment near the
except block explaining that decrypt_json() will call json.loads(decrypt(value))
and therefore decrypted corrupt JSON will re-trigger the JSON parse fallback at
read time, and that this is intentional because the runtime fallback will handle
it; reference the functions _json.loads, encrypt, decrypt_json, and
decrypt_if_present in the comment so future maintainers understand the
round-trip behavior and why some cells may still fail JSON parsing after
decryption.

frontend/src/app/auth/callback/page.tsx (1)

70-77: 💤 Low value

Silent failure fallback masks /api/auth/me errors.

When the /api/auth/me fetch fails (line 75), the code defaults onboardingCompleted = true, which could incorrectly skip onboarding for users who haven't completed it if the API is temporarily unavailable. Consider logging this case or retrying.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.
In `@frontend/src/app/auth/callback/page.tsx` around lines 70 - 77, The catch
block for the fetch('/api/auth/me') call in page.tsx silently sets
onboardingCompleted = true which can incorrectly skip onboarding on transient
API failures; update the catch to capture the error (e.g., catch (err)), log it
(console.error or your app logger) and set onboardingCompleted conservatively
(false or leave undefined) or implement a simple retry before deciding,
referencing the fetch('/api/auth/me') call and the onboardingCompleted/local
state update to locate the fix.

backend/routes/flashcards.py (1)

128-137: 💤 Low value

Silent pass on decrypt failure is acceptable but consider logging.

The try-except-pass on lines 133-136 silently ignores decryption failures for concept_notes. While this is intentional for legacy plaintext compatibility, the encryption module's docstring mentions "fallback logs a warning." Consider adding a logging statement here for consistency with the stated rollout observability.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.
In `@backend/routes/flashcards.py` around lines 128 - 137, The code silently
swallows exceptions when calling decrypt_json on d.get("concept_notes"); instead
add a warning log inside the except to surface the failure (include context like
the doc id/index and use exc_info=True or log the exception message) while
preserving the fallback behavior of leaving concept_notes unchanged; reference
the decrypt_json call and d["concept_notes"], and ensure you use the module
logger (e.g., obtain logging.getLogger(__name__) or reuse an existing logger
variable) before logging.

backend/routes/learn.py (1)

231-239: ⚡ Quick win

Use explicit None union type annotation.

PEP 484 prohibits implicit Optional. The type hint should use | None for clarity.

♻️ Proposed fix

-def save_message(session_id: str, role: str, content: str, graph_update: dict = None):+def save_message(session_id: str, role: str, content: str, graph_update: dict | None = None):

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.
In `@backend/routes/learn.py` around lines 231 - 239, Update the function
signature for save_message to use an explicit None union type for the
graph_update parameter: replace the implicit Optional style "graph_update: dict
= None" with the explicit union form "graph_update: dict | None = None"
(referencing the save_message function and the graph_update parameter) so the
type hint conforms to PEP 484; ensure no other code changes are required.

backend/tests/test_encryption.py (1)

99-106: Use specific exception type for tamper detection test.

The test currently catches Exception, which is too broad. AES-GCM tamper detection raises cryptography.exceptions.InvalidTag, and using the specific exception type makes the test more precise and prevents accidentally passing if a different exception is raised.

♻️ Proposed fix

 def test_tampered_ciphertext_raises():
import base64
+ from cryptography.exceptions import InvalidTag
ct = encryption.encrypt("secret")
raw = bytearray(base64.b64decode(ct))
raw[-1] ^= 0x01 # flip one bit in the tag
tampered = base64.b64encode(bytes(raw)).decode()
- with pytest.raises(Exception):+ with pytest.raises(InvalidTag):
encryption.decrypt(tampered)

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.
In `@backend/tests/test_encryption.py` around lines 99 - 106, The test
test_tampered_ciphertext_raises should assert the specific AES-GCM tamper
exception instead of catching all Exceptions: import InvalidTag from
cryptography.exceptions and change the context manager to with
pytest.raises(InvalidTag): calling encryption.decrypt(tampered). Keep the rest
of the test (encryption.encrypt and bit-flip tampering) unchanged so it still
exercises tamper detection.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@backend/db/migration_encryption_text_columns.sql`:
- Around line 13-27: The migration casts documents.concept_notes and
sessions.summary_json to TEXT but services/encryption.py's decrypt_json() lacks
the legacy-plaintext fallback, so pre-backfill rows will break; update
decrypt_json() (in backend/services/encryption.py) to detect and return
plaintext JSON when input isn't valid ciphertext (similar to the scalar
fallbacks used by decrypt_text()/decrypt_number()), or alternatively ensure the
DB backfill and enabling of readers are performed atomically so decrypt_json()
never sees legacy plaintext—modify either decrypt_json() to include a JSON
fallback helper or adjust the deployment/migration process to run the backfill
before enabling readers for documents.concept_notes and sessions.summary_json.
In `@backend/routes/auth.py`:
- Around line 228-229: The code is encrypting an empty string when
creds.refresh_token is None (calling encrypt("")), causing inconsistent handling
vs backfilled rows; change the assignment that sets "refresh_token" to either
call encrypt_if_present(creds.refresh_token) or keep a None value when
creds.refresh_token is falsy so empty strings are not encrypted—update the
object construction where "refresh_token" is set (referencing encrypt and
creds.refresh_token) to use encrypt_if_present or conditional preservation of
None to match the backfill behavior.
In `@backend/services/encryption.py`:
- Around line 116-117: decrypt_json currently assumes input is encrypted and
will raise if passed legacy plaintext JSON; update decrypt_json to mirror
decrypt_if_present by attempting to decrypt then json.loads, but on decryption
failure (or if decrypted result is invalid) fall back to json.loads(value) so
pre-encryption JSON still parses; locate the decrypt_json function and wrap its
call to decrypt(value) in a try/except (or check the decrypt result) and use
json.loads(value) as the fallback.
In `@backend/tests/conftest.py`:
- Around line 32-69: The current fixture only monkeypatches already-imported
route modules, leaving services.auth_guard itself untouched and causing
import-order dependent behavior; update the fixture to also monkeypatch the
functions on the services.auth_guard module (replace auth_guard._decode_session
with _decode_session_stub and auth_guard.get_session_user_id,
auth_guard.require_self, auth_guard.require_admin, and auth_guard.require_role
with the corresponding stubs/_require_role_stub) so any later-imported routes
that reference auth_guard will get the bypassed implementations; keep the
existing stubs (_decode_session_stub, _get_session_user_id_stub,
_require_self_stub, _require_admin_stub, _require_role_stub) and use
monkeypatch.setattr(auth_guard, "<name>", <stub>) for each symbol.
---
Outside diff comments:
In `@backend/routes/gradebook.py`:
- Around line 242-255: The POST handler currently inserts encrypted values
(using encrypt_if_present) and returns inserted[0] as-is, causing ciphertext to
be returned; after the insert in create_assignment (the block that builds
inserted = table("assignments").insert(...)), decrypt the stored fields before
returning by running points_possible, points_earned, and notes through the
corresponding decrypt helper (e.g., decrypt_if_present) and then return the
modified assignment object (rather than the raw inserted[0]); update the return
to return {"assignment": decrypted_assignment} so clients receive plaintext
fields consistent with read endpoints.
In `@backend/routes/learn.py`:
- Around line 525-532: The messages returned by resume_session are fetched into
msgs via table("messages").select but not decrypted; update resume_session to
reuse the decryption logic from get_conversation_history (or call
get_conversation_history(session_id) instead of returning raw msgs) so each
message's content is decrypted before returning. Locate the msgs variable and
the return that currently returns session_rows[0] and msgs, then either map over
msgs and replace each message's content with the decrypted value using the same
helper used by get_conversation_history, or delegate to get_conversation_history
to produce the decrypted messages, and return that result.
In `@backend/routes/quiz.py`:
- Around line 190-203: The student_name value used in the prompt can be None
because decrypt_if_present(user_rows[0]["name"]) may return None; before calling
.replace("{student_name}", student_name) ensure student_name is a non-null
string (e.g., coerce to a fallback like "Student" or "" if None) so template
replacement never receives None; update the code around where student_name is
assigned (the decrypt_if_present call and subsequent use in
ctx_prompt/_load_prompt) to coerce or default the value and use that sanitized
variable in the .replace call.
In `@backend/routes/social.py`:
- Around line 343-371: send_room_message currently stores body.user_name in
plaintext; update the insert in send_room_message to pass user_name through
encrypt_if_present (same pattern as text) so user_name is encrypted at rest.
Then update get_room_messages to call decrypt_if_present on the message row's
user_name and also on any reply snippet user_name (the reply_to handling
at/around where reply snippets are built) to return decrypted names to clients;
preserve null/None handling consistent with
encrypt_if_present/decrypt_if_present usage.
---
Nitpick comments:
In `@backend/db/backfill_encryption.py`:
- Line 91: The current call rows = table(table_name).select(",".join([pk,
*columns])) loads the entire table into memory; change the logic around
table(table_name).select to iterate in batches (use limit/offset or a cursor)
while selecting the same columns (referencing table_name, pk, columns and the
table(...) call) so you fetch e.g. BATCH_SIZE rows at a time, process them, then
advance the offset (or cursor) and repeat until no rows remain; ensure you
preserve ordering (order by pk) to make pagination deterministic and avoid
loading all rows into memory.
- Around line 162-172: When JSON parsing fails in backfill_encryption.py (the
_json.loads(v) exception path), we currently encrypt the raw string with
encrypt(v) so the value can round-trip through
decrypt_if_present/decrypt_json(); add a clear inline comment near the except
block explaining that decrypt_json() will call json.loads(decrypt(value)) and
therefore decrypted corrupt JSON will re-trigger the JSON parse fallback at read
time, and that this is intentional because the runtime fallback will handle it;
reference the functions _json.loads, encrypt, decrypt_json, and
decrypt_if_present in the comment so future maintainers understand the
round-trip behavior and why some cells may still fail JSON parsing after
decryption.
In `@backend/routes/flashcards.py`:
- Around line 128-137: The code silently swallows exceptions when calling
decrypt_json on d.get("concept_notes"); instead add a warning log inside the
except to surface the failure (include context like the doc id/index and use
exc_info=True or log the exception message) while preserving the fallback
behavior of leaving concept_notes unchanged; reference the decrypt_json call and
d["concept_notes"], and ensure you use the module logger (e.g., obtain
logging.getLogger(__name__) or reuse an existing logger variable) before
logging.
In `@backend/routes/learn.py`:
- Around line 231-239: Update the function signature for save_message to use an
explicit None union type for the graph_update parameter: replace the implicit
Optional style "graph_update: dict = None" with the explicit union form
"graph_update: dict | None = None" (referencing the save_message function and
the graph_update parameter) so the type hint conforms to PEP 484; ensure no
other code changes are required.
In `@backend/routes/onboarding.py`:
- Line 14: The function search_courses currently declares an unused parameter
request: Request which causes confusion; either remove the request parameter
from the function signature of search_courses (and any corresponding route
decorator/handler registration) or, if it's intentionally reserved for future
use (e.g., auth or middleware), add an inline comment above the signature
explaining why request is unused (e.g., "# request kept for future auth guard")
and prefix the variable with an underscore (request -> _request) to signal
intentional non-use. Update any callers or route mappings that expect the old
signature accordingly and ensure imports (Request) are cleaned up if removed.
In `@backend/services/auth_guard.py`:
- Around line 60-61: The except block currently swallows the original exception;
update the handler in auth_guard.py so the broad except Exception captures the
original exception (e.g., except Exception as e:) and re-raise the HTTPException
with exception chaining (raise HTTPException(status_code=401, detail="Not
authenticated") from e) to preserve the original traceback for debugging while
still returning 401 from the authentication function/handler.
In `@backend/tests/test_encryption.py`:
- Around line 99-106: The test test_tampered_ciphertext_raises should assert the
specific AES-GCM tamper exception instead of catching all Exceptions: import
InvalidTag from cryptography.exceptions and change the context manager to with
pytest.raises(InvalidTag): calling encryption.decrypt(tampered). Keep the rest
of the test (encryption.encrypt and bit-flip tampering) unchanged so it still
exercises tamper detection.
In `@frontend/src/app/auth/callback/page.tsx`:
- Around line 70-77: The catch block for the fetch('/api/auth/me') call in
page.tsx silently sets onboardingCompleted = true which can incorrectly skip
onboarding on transient API failures; update the catch to capture the error
(e.g., catch (err)), log it (console.error or your app logger) and set
onboardingCompleted conservatively (false or leave undefined) or implement a
simple retry before deciding, referencing the fetch('/api/auth/me') call and the
onboardingCompleted/local state update to locate the fix.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 0c1bef18-e8e8-4608-9891-9e17ab2b8476

📥 Commits

Reviewing files that changed from the base of the PR and between 1d184ef and ba27384.

📒 Files selected for processing (29)

• backend/.env.example
• backend/db/backfill_encryption.py
• backend/db/migration_encryption_text_columns.sql
• backend/requirements.txt
• backend/routes/admin.py
• backend/routes/auth.py
• backend/routes/calendar.py
• backend/routes/documents.py
• backend/routes/flashcards.py
• backend/routes/gradebook.py
• backend/routes/graph.py
• backend/routes/learn.py
• backend/routes/onboarding.py
• backend/routes/profile.py
• backend/routes/quiz.py
• backend/routes/social.py
• backend/routes/study_guide.py
• backend/services/auth_guard.py
• backend/services/encryption.py
• backend/tests/conftest.py
• backend/tests/test_encryption.py
• backend/tests/test_flashcard_import_routes.py
• backend/tests/test_learn_routes.py
• backend/tests/test_onboarding_routes.py
• backend/tests/test_shared_course_context.py
• backend/tests/test_social_messages.py
• docker-compose.yml
• docs/superpowers/plans/2026-05-03-aes-256-gcm-column-encryption.md
• frontend/src/app/auth/callback/page.tsx

[AndresL230]

Code review

Found 2 issues:

1. resume_session returns encrypted messages.content to the client without decrypting. save_message now writes encrypt_if_present(content) and get_conversation_history correctly applies decrypt_if_present, but resume_session selects id,role,content,created_at from the messages table and returns the rows as-is — users resuming a session will see base64 ciphertext instead of message text.

Sapling/backend/routes/learn.py

Lines 524 to 533 in ba27384

	msgs=table("messages").select(
	"id,role,content,created_at",
	filters={"session_id": f"eq.{session_id}"},
	order="created_at.asc",
	)
	return {
	"session": session_rows[0],
	"messages": msgs,
	}

2. The /auth/me endpoint signature changed to require a verified session (get_session_user_id(request) — accepts only an auth_token query param or sapling_session cookie), but frontend/src/middleware.ts still calls ${API_URL}/api/auth/me?user_id=... from edge middleware without forwarding either credential. Edge fetch() does not auto-forward browser cookies, so every protected-route navigation will receive 401 Not authenticated and fall into the redirectToSignin(request, 'session_expired') branch — full sign-in regression for approved users. The same ?user_id=... pattern is also used by frontend/src/app/api/auth/session/route.ts (fallback path) and frontend/src/context/UserContext.tsx.

Sapling/frontend/src/middleware.ts

Lines 43 to 62 in ba27384

	if(!API_URL)returnredirectToSignin(request,'google_not_configured')
	try{
	constcontroller=newAbortController()
	consttimeout=setTimeout(()=>controller.abort(),3000)
	letres: Response
	try{
	res=awaitfetch(
	`${API_URL}/api/auth/me?user_id=${encodeURIComponent(session.userId)}`,
	{signal: controller.signal},
	)
	}finally{
	clearTimeout(timeout)
	}
	if(!res.ok)returnredirectToSignin(request,'session_expired')
	constdata=awaitres.json()
	if(data.is_approved!==true)returnNextResponse.redirect(newURL('/pending',request.url))
	}catch{
	returnredirectToSignin(request,'signin_failed')
	}

Sapling/backend/services/auth_guard.py

Lines 16 to 51 in ba27384

	def_decode_session(request: Request) ->dict:
	"""Extract and verify the session token from query params or cookies."""
	token=request.query_params.get("auth_token") orrequest.cookies.get("sapling_session")
	ifnottokenornotSESSION_SECRET:
	raiseHTTPException(status_code=401, detail="Not authenticated")
	parts=token.split(".")
	iflen(parts) !=2:
	raiseHTTPException(status_code=401, detail="Invalid session token")
	payload_b64, sig_b64=parts
	# Verify signature
	expected_sig=_hmac.new(
	SESSION_SECRET.encode(), payload_b64.encode(), hashlib.sha256
	).digest()
	expected_b64=base64.urlsafe_b64encode(expected_sig).decode().rstrip("=")
	ifnot_hmac.compare_digest(sig_b64, expected_b64):
	raiseHTTPException(status_code=401, detail="Invalid session token")
	# Decode payload
	padding=4-len(payload_b64) %4
	ifpadding!=4:
	payload_b64+="="*padding
	try:
	payload=json.loads(base64.urlsafe_b64decode(payload_b64).decode())
	exceptException:
	raiseHTTPException(status_code=401, detail="Invalid session token")
	# Check expiry
	ifpayload.get("exp", 0) <int(_time.time()):
	raiseHTTPException(status_code=401, detail="Session expired")
	returnpayload

🤖 Generated with Claude Code

_{- If this code review was useful, please react with 👍. Otherwise, react with 👎.}

[coderabbitai]

Actionable comments posted: 2

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

frontend/src/app/api/auth/session/route.ts (1)

57-70: ⚠️ Potential issue | 🔴 Critical | 🏗️ Heavy lift

Align the sapling_session payload with backend auth_guard.

This route still mints the browser session through signSession(verifiedUserId), but frontend/src/lib/sessionToken.ts:32-41 signs { userId, exp } while backend/services/auth_guard.py:54-64 looks for payload["user_id"]. After this PR, /api/auth/me and the newly request-authenticated backend routes rely on that cookie, so the frontend will accept the session locally but the backend will 401 it and bounce approved users back to sign-in. Please make both sides read/write the same claim name, ideally with backward-compatible decoding during rollout.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.
In `@frontend/src/app/api/auth/session/route.ts` around lines 57 - 70, The
frontend is signing session tokens with a payload using the claim name userId
while the backend auth_guard expects user_id; update the signer used by
signSession (and the payload created in frontend's sessionToken.ts) to emit {
user_id, exp } instead of { userId, exp } or add backward-compatible decoding in
signSession so it also sets user_id when only userId exists, and ensure
verifyAuthToken/signSession continue to produce the cookie name sapling_session
with the same maxAge settings so backend(routes using auth_guard.py) will accept
the cookie during rollout.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@backend/routes/auth.py`:
- Around line 225-230: The calendar token reader must decrypt persisted
ciphertext before building the Credentials object: update the code that
constructs Credentials(...) in backend/routes/calendar.py (where it currently
passes token_row["access_token"] and token_row.get("refresh_token")) to call
decrypt on access_token and decrypt_if_present on refresh_token (or handle
None/empty), and convert the stored expires_at ISO string back to a datetime for
expiry; ensure the same decrypt helper used for encrypt_if_present is referenced
so refresh/decode works after the Google callback writes encrypted tokens.
---
Outside diff comments:
In `@frontend/src/app/api/auth/session/route.ts`:
- Around line 57-70: The frontend is signing session tokens with a payload using
the claim name userId while the backend auth_guard expects user_id; update the
signer used by signSession (and the payload created in frontend's
sessionToken.ts) to emit { user_id, exp } instead of { userId, exp } or add
backward-compatible decoding in signSession so it also sets user_id when only
userId exists, and ensure verifyAuthToken/signSession continue to produce the
cookie name sapling_session with the same maxAge settings so backend(routes
using auth_guard.py) will accept the cookie during rollout.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 01b8fe9a-7972-4263-9df1-4a7b944fcea4

📥 Commits

Reviewing files that changed from the base of the PR and between ba27384 and 43d9015.

📒 Files selected for processing (9)

• backend/routes/auth.py
• backend/routes/documents.py
• backend/routes/flashcards.py
• backend/routes/learn.py
• backend/services/encryption.py
• backend/tests/conftest.py
• backend/tests/test_flashcard_import_routes.py
• frontend/src/app/api/auth/session/route.ts
• frontend/src/middleware.ts

✅ Files skipped from review due to trivial changes (2)

• backend/tests/test_flashcard_import_routes.py
• backend/tests/conftest.py

[coderabbitai]

⚠️ Potential issue | 🟠 Major | 🏗️ Heavy lift

This will orphan pre-existing accounts that don't already have google_id.

When no google_id match exists, the new path always inserts user_{google_id} with is_approved = False. Any existing approved user created before google_id was populated will end up with a second account and lose access to their original courses, documents, graph, and approval state on next sign-in. This needs a transition strategy before merge, such as a one-time backfill of google_id or a temporary legacy-link path that can still find the old row.

[coderabbitai]

⚠️ Potential issue | 🔴 Critical | ⚡ Quick win

Update the calendar token reader in the same rollout.

These writes now persist ciphertext, but backend/routes/calendar.py:35-71 still passes token_row["access_token"] and token_row.get("refresh_token") directly into Credentials(...). After the first successful Google callback, calendar refresh/sync will start using encrypted strings and fail. Please land the matching decrypt-on-read change before shipping this write path.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.
In `@backend/routes/auth.py` around lines 225 - 230, The calendar token reader
must decrypt persisted ciphertext before building the Credentials object: update
the code that constructs Credentials(...) in backend/routes/calendar.py (where
it currently passes token_row["access_token"] and
token_row.get("refresh_token")) to call decrypt on access_token and
decrypt_if_present on refresh_token (or handle None/empty), and convert the
stored expires_at ISO string back to a datetime for expiry; ensure the same
decrypt helper used for encrypt_if_present is referenced so refresh/decode works
after the Google callback writes encrypted tokens.

[AndresL230]

Summary

Adds AES-256-GCM column-level encryption for user PII, OAuth tokens, assignment notes/points, document summaries/concept notes, session summaries, and chat messages. Includes encrypt-on-write + decrypt-on-read across all affected routes, a schema migration that retypes encrypted columns to TEXT, and an idempotent backfill script for existing rows.

Rollout — three things you need to do

1. What to apply to Supabase

Run one SQL file in the Supabase SQL editor: backend/db/migration_encryption_text_columns.sql. It contains four ALTER TABLE ... ALTER COLUMN ... TYPE TEXT USING ::TEXT statements.

Apply it once, before deploying the new code. The casts preserve existing rows as TEXT (e.g., 87.5 becomes the string "87.5"); the decrypt_if_present / decrypt_numeric fallbacks keep those legacy rows readable until you backfill.

2. Values you need to set

Just one new env var. ENCRYPTION_KEY = 64 hex chars (32 bytes). Generate it with:

python -c "import secrets; print(secrets.token_hex(32))"

Set it in:

• backend/.env for local dev (backend/.env.example already has the placeholder + the generation command).
• Wherever your backend actually runs in deploy (Cloudflare Workers/Pages env vars, Vercel, Fly, Railway, whatever — the same place SUPABASE_SERVICE_KEY is set today). docker-compose.yml already passes it through from backend/.env.

Two non-negotiables:

• The same key must be used everywhere your backend runs. Different keys = ciphertext written by one instance is unreadable by another.
• Never rotate or lose this key. Losing it permanently bricks every encrypted column. If you need to rotate, write a script that decrypts with the old key and re-encrypts with the new one in one transaction.

The backend will refuse to boot if ENCRYPTION_KEY is missing, not 64 chars, or not valid hex (intentional fail-fast).

3. The backfill script

backend/db/backfill_encryption.py. For each encrypted column on each table (users.name/email/bio/..., oauth_tokens.access_token/refresh_token, assignments.notes/points_*, documents.summary/concept_notes, sessions.summary_json, messages.content, room_messages.text), it:

1. Selects every row.
2. For each cell, calls decrypt(value) once.
3. If it succeeds → already encrypted → skip.
4. If it raises → the cell is still legacy plaintext → encrypt it and write back.

Prints counts per column. Idempotent — running it a second time changes nothing. Defaults to dry-run (counts only); --apply to actually write. --table users to do it in stages.

How to actually run all of this, in order

# 1. Generate and set the key
python -c "import secrets; print(secrets.token_hex(32))"# paste output as ENCRYPTION_KEY=... in backend/.env# AND set the same value in your deploy environment# 2. Apply the schema migration in Supabase# Dashboard → SQL Editor → paste contents of:# backend/db/migration_encryption_text_columns.sql → Run# 3. Deploy the new backend code (encryption wiring is on this branch)# 4. Backfill — first dry-run to see what will change:cd backend
.\venv\Scripts\python.exe -m db.backfill_encryption
# 5. Then actually apply:
.\venv\Scripts\python.exe -m db.backfill_encryption --apply

After the backfill completes successfully, the decrypt_if_present fallback-to-raw-value warnings should stop appearing in logs. That's the signal it worked.

Test plan

• Apply migration_encryption_text_columns.sql to a Supabase branch DB
• Set ENCRYPTION_KEY (64-hex) and confirm backend boots; confirm it refuses to boot when the var is missing/invalid
• Run backend tests: cd backend && python -m pytest tests/ -q (includes new test_encryption.py)
• Sign in via Google OAuth → confirm users.name/email written as ciphertext, /me returns plaintext
• Upload a document → confirm documents.summary/concept_notes ciphertext at rest, decrypt on library/study-guide/flashcards reads
• Sync calendar → confirm oauth_tokens.access_token/refresh_token and assignments.notes/points_* encrypted
• Send a room message + a learn-session message → confirm room_messages.text and messages.content encrypted
• Run backfill in dry-run on a copy of prod data, verify counts, then --apply and re-run to confirm idempotency (zero changes)
• Confirm decrypt_if_present fallback warnings disappear from logs after backfill

Summary by CodeRabbit

• New Features

  • End-to-end encryption for sensitive data (profiles, documents, sessions, messages, tokens).

• Improvements

  • Decryption in responses and encryption on save for many user-facing flows.
  • Tighter per-request authorization across endpoints and stricter ownership checks.

• Chores

  • Added encryption key configuration and dependency updates; adjusted schema to support encrypted values.

• Tests & Docs

  • Added encryption test coverage and an implementation/rollout plan.

[cloudflare-workers-and-pages]

Deploying with Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Preview URL	Updated (UTC)
✅ Deployment successful! View logs	frontend	43d9015	Commit Preview URL Branch Preview URL	May 03 2026, 07:57 PM

[coderabbitai]

📝 Walkthrough

Walkthrough

Adds AES-256-GCM column-level encryption: new encryption service, test coverage, env/docker wiring, a migration to TEXT for certain columns, a one-shot backfill CLI, and pervasive route changes to encrypt sensitive writes, decrypt reads, and enforce request-based authorization.

Changes

Encryption rollout & route wiring

Layer / File(s)	Summary
Data Shape / Schema Prep backend/db/migration_encryption_text_columns.sql	Retypes specific numeric/JSONB columns to TEXT using USING <col>::TEXT to allow storing ciphertext strings.
Dependencies backend/requirements.txt	Pins cryptography (>=42,<46).
Environment backend/.env.example, docker-compose.yml	Adds ENCRYPTION_KEY placeholder and passes ${ENCRYPTION_KEY} into the backend service.
Encryption Core backend/services/encryption.py	New AES-256-GCM helpers: key loader/validation, encrypt/decrypt, encrypt_if_present/decrypt_if_present, decrypt_numeric, encrypt_json/decrypt_json.
Backfill Tool backend/db/backfill_encryption.py	One-shot CLI that scans configured tables/columns, detects already-encrypted vs legacy plaintext/JSON/numeric values, and optionally writes encrypted values with --apply.
Auth Guard Tightening backend/services/auth_guard.py	get_session_user_id now requires a valid session token (no query-param fallback) and raises 401 on missing/invalid payload.
Route Integration (reads/writes & auth) backend/routes/*.py (auth, onboarding, profile, admin, social, quiz, learn, calendar, gradebook, documents, flashcards, study_guide, graph)	Handlers now accept Request where applicable, enforce require_self/session ownership, encrypt sensitive fields on write and decrypt on read, and narrow SELECT projections. OAuth tokens are decrypted for use and encrypted on refresh/storage. Several patch/allowlist behaviors adjusted to exclude sensitive fields.
Frontend adjustments frontend/src/app/auth/callback/page.tsx, frontend/src/app/api/auth/session/route.ts, frontend/src/middleware.ts	Auth callback no longer requires name param and fetches /api/auth/me from session; session route now requires/verifies authToken; middleware forwards sapling_session cookie to backend auth check.
Tests & Test Setup backend/tests/conftest.py, backend/tests/test_encryption.py, backend/tests/*	Deterministic test key in env, autouse fixture bypasses session auth for route tests, new encryption unit tests (string/JSON/numeric/nonce/tamper), and multiple route test updates to accommodate request-based auth and encrypted fields.
Docs / Plan docs/superpowers/plans/2026-05-03-aes-256-gcm-column-encryption.md	Comprehensive rollout plan, inventory of # ENCRYPTED LATER markers, migration/backfill instructions, and follow-up tasks.

Sequence Diagram

sequenceDiagram
participant Client
participant RouteHandler
participant AuthGuard
participant EncryptionSvc
participant Database
rect rgba(100, 150, 200, 0.5)
Note over Client,Database: Write path (encrypt before persist)
Client->>RouteHandler: POST /api/... (user_id, sensitive)
RouteHandler->>AuthGuard: require_self(user_id, request)
AuthGuard-->>RouteHandler: authorized
RouteHandler->>EncryptionSvc: encrypt(sensitive)
EncryptionSvc-->>RouteHandler: ciphertext
RouteHandler->>Database: INSERT/UPDATE (ciphertext)
Database-->>RouteHandler: OK
RouteHandler-->>Client: 200 (response with decrypted fields)
end
rect rgba(150, 200, 100, 0.5)
Note over Client,Database: Read path (decrypt on load)
Client->>RouteHandler: GET /api/.../{user_id}
RouteHandler->>AuthGuard: require_self(user_id, request)
AuthGuard-->>RouteHandler: authorized
RouteHandler->>Database: SELECT (ciphertext_field)
Database-->>RouteHandler: row with ciphertext
RouteHandler->>EncryptionSvc: decrypt_if_present(ciphertext)
EncryptionSvc-->>RouteHandler: plaintext or legacy value
RouteHandler-->>Client: 200 (plaintext)
end
rect rgba(200, 100, 100, 0.5)
Note over RouteHandler,EncryptionSvc: Legacy plaintext fallback
RouteHandler->>EncryptionSvc: decrypt_if_present(legacy_plaintext)
EncryptionSvc-->>RouteHandler: returns original plaintext (logs warning)
end

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Possibly related PRs

• adding approval gate for closed beta #56: Overlaps changes to backend/routes/auth.py GET /me (authorization and returned fields).
• Course ID schema migration + calendar assignment normalization #53: Overlaps calendar assignment flows and OAuth token handling in backend/routes/calendar.py.
• Frontend revamp (M1-M9 + deferred items + production hardening) #62: Related frontend session handling changes to frontend/src/app/api/auth/session/route.ts (cookie/session verification).

Poem

🐰
I hopped through code at dawn's first light,
Wrapped secrets snug in AES so tight,
Nonces fresh, each byte takes flight,
Now data sleeps secure each night.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 16.56% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'feat: AES-256-GCM column-level encryption for user PII' directly and clearly summarizes the main feature being added—column-level encryption for sensitive user data.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description check	✅ Passed	The PR description comprehensively covers what the PR does, why, rollout steps, environment configuration, backfill instructions, and test plan—all aligned with the description template structure.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/aes-256-gcm-encryption

Tip

💬 Introducing Slack Agent: The best way for teams to turn conversations into code.

Slack Agent is built on CodeRabbit's deep understanding of your code, so your team can collaborate across the entire SDLC without losing context.

• Generate code and open pull requests
• Plan features and break down work
• Investigate incidents and troubleshoot customer tickets together
• Automate recurring tasks and respond to alerts with triggers
• Summarize progress and report instantly

Built for teams:

• Shared memory across your entire org—no repeating context
• Per-thread sandboxes to safely plan and execute work
• Governance built-in—scoped access, auditability, and budget controls

One agent for your entire SDLC. Right inside Slack.

👉 Get started

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 4

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (4)

backend/routes/quiz.py (1)

190-203: ⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Guard student_name against nulls before template replacement.

decrypt_if_present() can return None. If users.name is null, the .replace("{student_name}", student_name) call raises TypeError after the quiz attempt and mastery updates have already been persisted.

Suggested fix

- student_name = decrypt_if_present(user_rows[0]["name"]) if user_rows else "Student"+ student_name = (+ decrypt_if_present(user_rows[0].get("name")) or "Student"+ if user_rows+ else "Student"+ )

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.
In `@backend/routes/quiz.py` around lines 190 - 203, The student_name value used
in the prompt can be None because decrypt_if_present(user_rows[0]["name"]) may
return None; before calling .replace("{student_name}", student_name) ensure
student_name is a non-null string (e.g., coerce to a fallback like "Student" or
"" if None) so template replacement never receives None; update the code around
where student_name is assigned (the decrypt_if_present call and subsequent use
in ctx_prompt/_load_prompt) to coerce or default the value and use that
sanitized variable in the .replace call.

backend/routes/gradebook.py (1)

242-255: ⚠️ Potential issue | 🟠 Major | ⚡ Quick win

Return decrypted fields from create_assignment().

This route now writes encrypted points_possible, points_earned, and notes, then returns inserted[0] verbatim. Any client that uses the POST response to update local state will receive ciphertext instead of the values it just submitted, while the read endpoints return plaintext.

Suggested fix

 inserted = table("assignments").insert({
"id": new_id,
"user_id": body.user_id,
"course_id": body.course_id,
"title": body.title,
"category_id": body.category_id,
"points_possible": encrypt_if_present(body.points_possible),
"points_earned": encrypt_if_present(body.points_earned),
"due_date": body.due_date,
"assignment_type": body.assignment_type,
"notes": encrypt_if_present(body.notes),
"source": "manual",
})
- return {"assignment": inserted[0] if inserted else None}+ assignment = inserted[0] if inserted else None+ if assignment:+ assignment["points_possible"] = decrypt_numeric(assignment.get("points_possible"))+ assignment["points_earned"] = decrypt_numeric(assignment.get("points_earned"))+ assignment["notes"] = decrypt_if_present(assignment.get("notes"))+ return {"assignment": assignment}

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.
In `@backend/routes/gradebook.py` around lines 242 - 255, The POST handler
currently inserts encrypted values (using encrypt_if_present) and returns
inserted[0] as-is, causing ciphertext to be returned; after the insert in
create_assignment (the block that builds inserted =
table("assignments").insert(...)), decrypt the stored fields before returning by
running points_possible, points_earned, and notes through the corresponding
decrypt helper (e.g., decrypt_if_present) and then return the modified
assignment object (rather than the raw inserted[0]); update the return to return
{"assignment": decrypted_assignment} so clients receive plaintext fields
consistent with read endpoints.

backend/routes/learn.py (1)

525-532: ⚠️ Potential issue | 🟠 Major | ⚡ Quick win

Messages returned by resume_session are not decrypted.

When resuming a persisted session, the messages fetched from the database have encrypted content but are returned directly without decryption. This is inconsistent with get_conversation_history which decrypts message content.

🐛 Proposed fix

 msgs = table("messages").select(
"id,role,content,created_at",
filters={"session_id": f"eq.{session_id}"},
order="created_at.asc",
)
+ for m in msgs:+ m["content"] = decrypt_if_present(m.get("content"))
return {
"session": session_rows[0],
"messages": msgs,
}

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.
In `@backend/routes/learn.py` around lines 525 - 532, The messages returned by
resume_session are fetched into msgs via table("messages").select but not
decrypted; update resume_session to reuse the decryption logic from
get_conversation_history (or call get_conversation_history(session_id) instead
of returning raw msgs) so each message's content is decrypted before returning.
Locate the msgs variable and the return that currently returns session_rows[0]
and msgs, then either map over msgs and replace each message's content with the
decrypted value using the same helper used by get_conversation_history, or
delegate to get_conversation_history to produce the decrypted messages, and
return that result.

backend/routes/social.py (1)

343-371: ⚠️ Potential issue | 🟠 Major

user_name is stored unencrypted in room_messages.

The message text is encrypted but body.user_name is stored in plaintext. This is inconsistent with the PR's goal of encrypting PII. User names are PII and should be encrypted at rest.

This also requires updating get_room_messages to decrypt user_name in the message rows (line 290) and reply snippets (line 320).

🔒 Proposed fix to encrypt user_name

 row = table("room_messages").insert({
"room_id": room_id,
"user_id": body.user_id,
- "user_name": body.user_name,+ "user_name": encrypt_if_present(body.user_name),
"text": encrypt_if_present(body.text or None),
"image_url": body.image_url or None,
"reply_to_id": body.reply_to_id or None,
})
if row:
row[0]["text"] = decrypt_if_present(row[0].get("text"))
+ row[0]["user_name"] = decrypt_if_present(row[0].get("user_name"))

In get_room_messages, decrypt user_name when retrieving message rows and reply snippets.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.
In `@backend/routes/social.py` around lines 343 - 371, send_room_message currently
stores body.user_name in plaintext; update the insert in send_room_message to
pass user_name through encrypt_if_present (same pattern as text) so user_name is
encrypted at rest. Then update get_room_messages to call decrypt_if_present on
the message row's user_name and also on any reply snippet user_name (the
reply_to handling at/around where reply snippets are built) to return decrypted
names to clients; preserve null/None handling consistent with
encrypt_if_present/decrypt_if_present usage.

🧹 Nitpick comments (8)

backend/services/auth_guard.py (1)

60-61: 💤 Low value

Add exception chaining for better error tracing.

While catching a broad Exception is acceptable here (any decode failure should yield 401), using raise ... from would preserve the original exception context for debugging.

♻️ Suggested improvement

- except Exception:- raise HTTPException(status_code=401, detail="Not authenticated")+ except Exception as exc:+ raise HTTPException(status_code=401, detail="Not authenticated") from exc

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.
In `@backend/services/auth_guard.py` around lines 60 - 61, The except block
currently swallows the original exception; update the handler in auth_guard.py
so the broad except Exception captures the original exception (e.g., except
Exception as e:) and re-raise the HTTPException with exception chaining (raise
HTTPException(status_code=401, detail="Not authenticated") from e) to preserve
the original traceback for debugging while still returning 401 from the
authentication function/handler.

backend/routes/onboarding.py (1)

14-14: 💤 Low value

Unused request parameter in search_courses.

The request: Request parameter is accepted but never used in this function. If this is intentional for consistency or future auth guards, consider adding a comment. Otherwise, remove it to avoid confusion.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.
In `@backend/routes/onboarding.py` at line 14, The function search_courses
currently declares an unused parameter request: Request which causes confusion;
either remove the request parameter from the function signature of
search_courses (and any corresponding route decorator/handler registration) or,
if it's intentionally reserved for future use (e.g., auth or middleware), add an
inline comment above the signature explaining why request is unused (e.g., "#
request kept for future auth guard") and prefix the variable with an underscore
(request -> _request) to signal intentional non-use. Update any callers or route
mappings that expect the old signature accordingly and ensure imports (Request)
are cleaned up if removed.

backend/db/backfill_encryption.py (2)

91-91: 🏗️ Heavy lift

No pagination — large tables may cause memory/timeout issues.

table(table_name).select(...) on line 91 (and similar calls) loads all rows into memory. For tables with millions of rows (e.g., messages, room_messages), this could exhaust memory or timeout.

Consider adding batching with limit and offset, or using cursor-based pagination:

Example batch approach

BATCH_SIZE=1000offset=0whileTrue:
rows=table(table_name).select(
",".join([pk, *columns]),
limit=BATCH_SIZE,
offset=offset,
order=f"{pk}.asc"
) or []
ifnotrows:
break# process rows...offset+=BATCH_SIZE

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.
In `@backend/db/backfill_encryption.py` at line 91, The current call rows =
table(table_name).select(",".join([pk, *columns])) loads the entire table into
memory; change the logic around table(table_name).select to iterate in batches
(use limit/offset or a cursor) while selecting the same columns (referencing
table_name, pk, columns and the table(...) call) so you fetch e.g. BATCH_SIZE
rows at a time, process them, then advance the offset (or cursor) and repeat
until no rows remain; ensure you preserve ordering (order by pk) to make
pagination deterministic and avoid loading all rows into memory.

---

162-172: 💤 Low value

Corrupt JSON encrypted as raw string may cause decrypt mismatch.

When JSON parsing fails (line 164), the raw string is encrypted via encrypt(v) (line 169). However, reads use decrypt_json() which expects json.loads(decrypt(value)). Decrypting will succeed, but json.loads will fail on the corrupt JSON, triggering the fallback path.

This is acceptable since the fallback handles it, but documenting this behavior would help future maintainers understand why some cells fail JSON parsing after decryption.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.
In `@backend/db/backfill_encryption.py` around lines 162 - 172, When JSON parsing
fails in backfill_encryption.py (the _json.loads(v) exception path), we
currently encrypt the raw string with encrypt(v) so the value can round-trip
through decrypt_if_present/decrypt_json(); add a clear inline comment near the
except block explaining that decrypt_json() will call json.loads(decrypt(value))
and therefore decrypted corrupt JSON will re-trigger the JSON parse fallback at
read time, and that this is intentional because the runtime fallback will handle
it; reference the functions _json.loads, encrypt, decrypt_json, and
decrypt_if_present in the comment so future maintainers understand the
round-trip behavior and why some cells may still fail JSON parsing after
decryption.

frontend/src/app/auth/callback/page.tsx (1)

70-77: 💤 Low value

Silent failure fallback masks /api/auth/me errors.

When the /api/auth/me fetch fails (line 75), the code defaults onboardingCompleted = true, which could incorrectly skip onboarding for users who haven't completed it if the API is temporarily unavailable. Consider logging this case or retrying.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.
In `@frontend/src/app/auth/callback/page.tsx` around lines 70 - 77, The catch
block for the fetch('/api/auth/me') call in page.tsx silently sets
onboardingCompleted = true which can incorrectly skip onboarding on transient
API failures; update the catch to capture the error (e.g., catch (err)), log it
(console.error or your app logger) and set onboardingCompleted conservatively
(false or leave undefined) or implement a simple retry before deciding,
referencing the fetch('/api/auth/me') call and the onboardingCompleted/local
state update to locate the fix.

backend/routes/flashcards.py (1)

128-137: 💤 Low value

Silent pass on decrypt failure is acceptable but consider logging.

The try-except-pass on lines 133-136 silently ignores decryption failures for concept_notes. While this is intentional for legacy plaintext compatibility, the encryption module's docstring mentions "fallback logs a warning." Consider adding a logging statement here for consistency with the stated rollout observability.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.
In `@backend/routes/flashcards.py` around lines 128 - 137, The code silently
swallows exceptions when calling decrypt_json on d.get("concept_notes"); instead
add a warning log inside the except to surface the failure (include context like
the doc id/index and use exc_info=True or log the exception message) while
preserving the fallback behavior of leaving concept_notes unchanged; reference
the decrypt_json call and d["concept_notes"], and ensure you use the module
logger (e.g., obtain logging.getLogger(__name__) or reuse an existing logger
variable) before logging.

backend/routes/learn.py (1)

231-239: ⚡ Quick win

Use explicit None union type annotation.

PEP 484 prohibits implicit Optional. The type hint should use | None for clarity.

♻️ Proposed fix

-def save_message(session_id: str, role: str, content: str, graph_update: dict = None):+def save_message(session_id: str, role: str, content: str, graph_update: dict | None = None):

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.
In `@backend/routes/learn.py` around lines 231 - 239, Update the function
signature for save_message to use an explicit None union type for the
graph_update parameter: replace the implicit Optional style "graph_update: dict
= None" with the explicit union form "graph_update: dict | None = None"
(referencing the save_message function and the graph_update parameter) so the
type hint conforms to PEP 484; ensure no other code changes are required.

backend/tests/test_encryption.py (1)

99-106: Use specific exception type for tamper detection test.

The test currently catches Exception, which is too broad. AES-GCM tamper detection raises cryptography.exceptions.InvalidTag, and using the specific exception type makes the test more precise and prevents accidentally passing if a different exception is raised.

♻️ Proposed fix

 def test_tampered_ciphertext_raises():
import base64
+ from cryptography.exceptions import InvalidTag
ct = encryption.encrypt("secret")
raw = bytearray(base64.b64decode(ct))
raw[-1] ^= 0x01 # flip one bit in the tag
tampered = base64.b64encode(bytes(raw)).decode()
- with pytest.raises(Exception):+ with pytest.raises(InvalidTag):
encryption.decrypt(tampered)

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.
In `@backend/tests/test_encryption.py` around lines 99 - 106, The test
test_tampered_ciphertext_raises should assert the specific AES-GCM tamper
exception instead of catching all Exceptions: import InvalidTag from
cryptography.exceptions and change the context manager to with
pytest.raises(InvalidTag): calling encryption.decrypt(tampered). Keep the rest
of the test (encryption.encrypt and bit-flip tampering) unchanged so it still
exercises tamper detection.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@backend/db/migration_encryption_text_columns.sql`:
- Around line 13-27: The migration casts documents.concept_notes and
sessions.summary_json to TEXT but services/encryption.py's decrypt_json() lacks
the legacy-plaintext fallback, so pre-backfill rows will break; update
decrypt_json() (in backend/services/encryption.py) to detect and return
plaintext JSON when input isn't valid ciphertext (similar to the scalar
fallbacks used by decrypt_text()/decrypt_number()), or alternatively ensure the
DB backfill and enabling of readers are performed atomically so decrypt_json()
never sees legacy plaintext—modify either decrypt_json() to include a JSON
fallback helper or adjust the deployment/migration process to run the backfill
before enabling readers for documents.concept_notes and sessions.summary_json.
In `@backend/routes/auth.py`:
- Around line 228-229: The code is encrypting an empty string when
creds.refresh_token is None (calling encrypt("")), causing inconsistent handling
vs backfilled rows; change the assignment that sets "refresh_token" to either
call encrypt_if_present(creds.refresh_token) or keep a None value when
creds.refresh_token is falsy so empty strings are not encrypted—update the
object construction where "refresh_token" is set (referencing encrypt and
creds.refresh_token) to use encrypt_if_present or conditional preservation of
None to match the backfill behavior.
In `@backend/services/encryption.py`:
- Around line 116-117: decrypt_json currently assumes input is encrypted and
will raise if passed legacy plaintext JSON; update decrypt_json to mirror
decrypt_if_present by attempting to decrypt then json.loads, but on decryption
failure (or if decrypted result is invalid) fall back to json.loads(value) so
pre-encryption JSON still parses; locate the decrypt_json function and wrap its
call to decrypt(value) in a try/except (or check the decrypt result) and use
json.loads(value) as the fallback.
In `@backend/tests/conftest.py`:
- Around line 32-69: The current fixture only monkeypatches already-imported
route modules, leaving services.auth_guard itself untouched and causing
import-order dependent behavior; update the fixture to also monkeypatch the
functions on the services.auth_guard module (replace auth_guard._decode_session
with _decode_session_stub and auth_guard.get_session_user_id,
auth_guard.require_self, auth_guard.require_admin, and auth_guard.require_role
with the corresponding stubs/_require_role_stub) so any later-imported routes
that reference auth_guard will get the bypassed implementations; keep the
existing stubs (_decode_session_stub, _get_session_user_id_stub,
_require_self_stub, _require_admin_stub, _require_role_stub) and use
monkeypatch.setattr(auth_guard, "<name>", <stub>) for each symbol.
---
Outside diff comments:
In `@backend/routes/gradebook.py`:
- Around line 242-255: The POST handler currently inserts encrypted values
(using encrypt_if_present) and returns inserted[0] as-is, causing ciphertext to
be returned; after the insert in create_assignment (the block that builds
inserted = table("assignments").insert(...)), decrypt the stored fields before
returning by running points_possible, points_earned, and notes through the
corresponding decrypt helper (e.g., decrypt_if_present) and then return the
modified assignment object (rather than the raw inserted[0]); update the return
to return {"assignment": decrypted_assignment} so clients receive plaintext
fields consistent with read endpoints.
In `@backend/routes/learn.py`:
- Around line 525-532: The messages returned by resume_session are fetched into
msgs via table("messages").select but not decrypted; update resume_session to
reuse the decryption logic from get_conversation_history (or call
get_conversation_history(session_id) instead of returning raw msgs) so each
message's content is decrypted before returning. Locate the msgs variable and
the return that currently returns session_rows[0] and msgs, then either map over
msgs and replace each message's content with the decrypted value using the same
helper used by get_conversation_history, or delegate to get_conversation_history
to produce the decrypted messages, and return that result.
In `@backend/routes/quiz.py`:
- Around line 190-203: The student_name value used in the prompt can be None
because decrypt_if_present(user_rows[0]["name"]) may return None; before calling
.replace("{student_name}", student_name) ensure student_name is a non-null
string (e.g., coerce to a fallback like "Student" or "" if None) so template
replacement never receives None; update the code around where student_name is
assigned (the decrypt_if_present call and subsequent use in
ctx_prompt/_load_prompt) to coerce or default the value and use that sanitized
variable in the .replace call.
In `@backend/routes/social.py`:
- Around line 343-371: send_room_message currently stores body.user_name in
plaintext; update the insert in send_room_message to pass user_name through
encrypt_if_present (same pattern as text) so user_name is encrypted at rest.
Then update get_room_messages to call decrypt_if_present on the message row's
user_name and also on any reply snippet user_name (the reply_to handling
at/around where reply snippets are built) to return decrypted names to clients;
preserve null/None handling consistent with
encrypt_if_present/decrypt_if_present usage.
---
Nitpick comments:
In `@backend/db/backfill_encryption.py`:
- Line 91: The current call rows = table(table_name).select(",".join([pk,
*columns])) loads the entire table into memory; change the logic around
table(table_name).select to iterate in batches (use limit/offset or a cursor)
while selecting the same columns (referencing table_name, pk, columns and the
table(...) call) so you fetch e.g. BATCH_SIZE rows at a time, process them, then
advance the offset (or cursor) and repeat until no rows remain; ensure you
preserve ordering (order by pk) to make pagination deterministic and avoid
loading all rows into memory.
- Around line 162-172: When JSON parsing fails in backfill_encryption.py (the
_json.loads(v) exception path), we currently encrypt the raw string with
encrypt(v) so the value can round-trip through
decrypt_if_present/decrypt_json(); add a clear inline comment near the except
block explaining that decrypt_json() will call json.loads(decrypt(value)) and
therefore decrypted corrupt JSON will re-trigger the JSON parse fallback at read
time, and that this is intentional because the runtime fallback will handle it;
reference the functions _json.loads, encrypt, decrypt_json, and
decrypt_if_present in the comment so future maintainers understand the
round-trip behavior and why some cells may still fail JSON parsing after
decryption.
In `@backend/routes/flashcards.py`:
- Around line 128-137: The code silently swallows exceptions when calling
decrypt_json on d.get("concept_notes"); instead add a warning log inside the
except to surface the failure (include context like the doc id/index and use
exc_info=True or log the exception message) while preserving the fallback
behavior of leaving concept_notes unchanged; reference the decrypt_json call and
d["concept_notes"], and ensure you use the module logger (e.g., obtain
logging.getLogger(__name__) or reuse an existing logger variable) before
logging.
In `@backend/routes/learn.py`:
- Around line 231-239: Update the function signature for save_message to use an
explicit None union type for the graph_update parameter: replace the implicit
Optional style "graph_update: dict = None" with the explicit union form
"graph_update: dict | None = None" (referencing the save_message function and
the graph_update parameter) so the type hint conforms to PEP 484; ensure no
other code changes are required.
In `@backend/routes/onboarding.py`:
- Line 14: The function search_courses currently declares an unused parameter
request: Request which causes confusion; either remove the request parameter
from the function signature of search_courses (and any corresponding route
decorator/handler registration) or, if it's intentionally reserved for future
use (e.g., auth or middleware), add an inline comment above the signature
explaining why request is unused (e.g., "# request kept for future auth guard")
and prefix the variable with an underscore (request -> _request) to signal
intentional non-use. Update any callers or route mappings that expect the old
signature accordingly and ensure imports (Request) are cleaned up if removed.
In `@backend/services/auth_guard.py`:
- Around line 60-61: The except block currently swallows the original exception;
update the handler in auth_guard.py so the broad except Exception captures the
original exception (e.g., except Exception as e:) and re-raise the HTTPException
with exception chaining (raise HTTPException(status_code=401, detail="Not
authenticated") from e) to preserve the original traceback for debugging while
still returning 401 from the authentication function/handler.
In `@backend/tests/test_encryption.py`:
- Around line 99-106: The test test_tampered_ciphertext_raises should assert the
specific AES-GCM tamper exception instead of catching all Exceptions: import
InvalidTag from cryptography.exceptions and change the context manager to with
pytest.raises(InvalidTag): calling encryption.decrypt(tampered). Keep the rest
of the test (encryption.encrypt and bit-flip tampering) unchanged so it still
exercises tamper detection.
In `@frontend/src/app/auth/callback/page.tsx`:
- Around line 70-77: The catch block for the fetch('/api/auth/me') call in
page.tsx silently sets onboardingCompleted = true which can incorrectly skip
onboarding on transient API failures; update the catch to capture the error
(e.g., catch (err)), log it (console.error or your app logger) and set
onboardingCompleted conservatively (false or leave undefined) or implement a
simple retry before deciding, referencing the fetch('/api/auth/me') call and the
onboardingCompleted/local state update to locate the fix.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 0c1bef18-e8e8-4608-9891-9e17ab2b8476

📥 Commits

Reviewing files that changed from the base of the PR and between 1d184ef and ba27384.

📒 Files selected for processing (29)

• backend/.env.example
• backend/db/backfill_encryption.py
• backend/db/migration_encryption_text_columns.sql
• backend/requirements.txt
• backend/routes/admin.py
• backend/routes/auth.py
• backend/routes/calendar.py
• backend/routes/documents.py
• backend/routes/flashcards.py
• backend/routes/gradebook.py
• backend/routes/graph.py
• backend/routes/learn.py
• backend/routes/onboarding.py
• backend/routes/profile.py
• backend/routes/quiz.py
• backend/routes/social.py
• backend/routes/study_guide.py
• backend/services/auth_guard.py
• backend/services/encryption.py
• backend/tests/conftest.py
• backend/tests/test_encryption.py
• backend/tests/test_flashcard_import_routes.py
• backend/tests/test_learn_routes.py
• backend/tests/test_onboarding_routes.py
• backend/tests/test_shared_course_context.py
• backend/tests/test_social_messages.py
• docker-compose.yml
• docs/superpowers/plans/2026-05-03-aes-256-gcm-column-encryption.md
• frontend/src/app/auth/callback/page.tsx

[AndresL230]

Code review

Found 2 issues:

1. resume_session returns encrypted messages.content to the client without decrypting. save_message now writes encrypt_if_present(content) and get_conversation_history correctly applies decrypt_if_present, but resume_session selects id,role,content,created_at from the messages table and returns the rows as-is — users resuming a session will see base64 ciphertext instead of message text.

Sapling/backend/routes/learn.py

Lines 524 to 533 in ba27384

	msgs=table("messages").select(
	"id,role,content,created_at",
	filters={"session_id": f"eq.{session_id}"},
	order="created_at.asc",
	)
	return {
	"session": session_rows[0],
	"messages": msgs,
	}

2. The /auth/me endpoint signature changed to require a verified session (get_session_user_id(request) — accepts only an auth_token query param or sapling_session cookie), but frontend/src/middleware.ts still calls ${API_URL}/api/auth/me?user_id=... from edge middleware without forwarding either credential. Edge fetch() does not auto-forward browser cookies, so every protected-route navigation will receive 401 Not authenticated and fall into the redirectToSignin(request, 'session_expired') branch — full sign-in regression for approved users. The same ?user_id=... pattern is also used by frontend/src/app/api/auth/session/route.ts (fallback path) and frontend/src/context/UserContext.tsx.

Sapling/frontend/src/middleware.ts

Lines 43 to 62 in ba27384

	if(!API_URL)returnredirectToSignin(request,'google_not_configured')
	try{
	constcontroller=newAbortController()
	consttimeout=setTimeout(()=>controller.abort(),3000)
	letres: Response
	try{
	res=awaitfetch(
	`${API_URL}/api/auth/me?user_id=${encodeURIComponent(session.userId)}`,
	{signal: controller.signal},
	)
	}finally{
	clearTimeout(timeout)
	}
	if(!res.ok)returnredirectToSignin(request,'session_expired')
	constdata=awaitres.json()
	if(data.is_approved!==true)returnNextResponse.redirect(newURL('/pending',request.url))
	}catch{
	returnredirectToSignin(request,'signin_failed')
	}

Sapling/backend/services/auth_guard.py

Lines 16 to 51 in ba27384

	def_decode_session(request: Request) ->dict:
	"""Extract and verify the session token from query params or cookies."""
	token=request.query_params.get("auth_token") orrequest.cookies.get("sapling_session")
	ifnottokenornotSESSION_SECRET:
	raiseHTTPException(status_code=401, detail="Not authenticated")
	parts=token.split(".")
	iflen(parts) !=2:
	raiseHTTPException(status_code=401, detail="Invalid session token")
	payload_b64, sig_b64=parts
	# Verify signature
	expected_sig=_hmac.new(
	SESSION_SECRET.encode(), payload_b64.encode(), hashlib.sha256
	).digest()
	expected_b64=base64.urlsafe_b64encode(expected_sig).decode().rstrip("=")
	ifnot_hmac.compare_digest(sig_b64, expected_b64):
	raiseHTTPException(status_code=401, detail="Invalid session token")
	# Decode payload
	padding=4-len(payload_b64) %4
	ifpadding!=4:
	payload_b64+="="*padding
	try:
	payload=json.loads(base64.urlsafe_b64decode(payload_b64).decode())
	exceptException:
	raiseHTTPException(status_code=401, detail="Invalid session token")
	# Check expiry
	ifpayload.get("exp", 0) <int(_time.time()):
	raiseHTTPException(status_code=401, detail="Session expired")
	returnpayload

🤖 Generated with Claude Code

_{- If this code review was useful, please react with 👍. Otherwise, react with 👎.}

[coderabbitai]

Actionable comments posted: 2

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

frontend/src/app/api/auth/session/route.ts (1)

57-70: ⚠️ Potential issue | 🔴 Critical | 🏗️ Heavy lift

Align the sapling_session payload with backend auth_guard.

This route still mints the browser session through signSession(verifiedUserId), but frontend/src/lib/sessionToken.ts:32-41 signs { userId, exp } while backend/services/auth_guard.py:54-64 looks for payload["user_id"]. After this PR, /api/auth/me and the newly request-authenticated backend routes rely on that cookie, so the frontend will accept the session locally but the backend will 401 it and bounce approved users back to sign-in. Please make both sides read/write the same claim name, ideally with backward-compatible decoding during rollout.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.
In `@frontend/src/app/api/auth/session/route.ts` around lines 57 - 70, The
frontend is signing session tokens with a payload using the claim name userId
while the backend auth_guard expects user_id; update the signer used by
signSession (and the payload created in frontend's sessionToken.ts) to emit {
user_id, exp } instead of { userId, exp } or add backward-compatible decoding in
signSession so it also sets user_id when only userId exists, and ensure
verifyAuthToken/signSession continue to produce the cookie name sapling_session
with the same maxAge settings so backend(routes using auth_guard.py) will accept
the cookie during rollout.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@backend/routes/auth.py`:
- Around line 225-230: The calendar token reader must decrypt persisted
ciphertext before building the Credentials object: update the code that
constructs Credentials(...) in backend/routes/calendar.py (where it currently
passes token_row["access_token"] and token_row.get("refresh_token")) to call
decrypt on access_token and decrypt_if_present on refresh_token (or handle
None/empty), and convert the stored expires_at ISO string back to a datetime for
expiry; ensure the same decrypt helper used for encrypt_if_present is referenced
so refresh/decode works after the Google callback writes encrypted tokens.
---
Outside diff comments:
In `@frontend/src/app/api/auth/session/route.ts`:
- Around line 57-70: The frontend is signing session tokens with a payload using
the claim name userId while the backend auth_guard expects user_id; update the
signer used by signSession (and the payload created in frontend's
sessionToken.ts) to emit { user_id, exp } instead of { userId, exp } or add
backward-compatible decoding in signSession so it also sets user_id when only
userId exists, and ensure verifyAuthToken/signSession continue to produce the
cookie name sapling_session with the same maxAge settings so backend(routes
using auth_guard.py) will accept the cookie during rollout.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 01b8fe9a-7972-4263-9df1-4a7b944fcea4

📥 Commits

Reviewing files that changed from the base of the PR and between ba27384 and 43d9015.

📒 Files selected for processing (9)

• backend/routes/auth.py
• backend/routes/documents.py
• backend/routes/flashcards.py
• backend/routes/learn.py
• backend/services/encryption.py
• backend/tests/conftest.py
• backend/tests/test_flashcard_import_routes.py
• frontend/src/app/api/auth/session/route.ts
• frontend/src/middleware.ts

✅ Files skipped from review due to trivial changes (2)

• backend/tests/test_flashcard_import_routes.py
• backend/tests/conftest.py

[coderabbitai]

⚠️ Potential issue | 🟠 Major | 🏗️ Heavy lift

This will orphan pre-existing accounts that don't already have google_id.

When no google_id match exists, the new path always inserts user_{google_id} with is_approved = False. Any existing approved user created before google_id was populated will end up with a second account and lose access to their original courses, documents, graph, and approval state on next sign-in. This needs a transition strategy before merge, such as a one-time backfill of google_id or a temporary legacy-link path that can still find the old row.

[coderabbitai]

⚠️ Potential issue | 🔴 Critical | ⚡ Quick win

Update the calendar token reader in the same rollout.

These writes now persist ciphertext, but backend/routes/calendar.py:35-71 still passes token_row["access_token"] and token_row.get("refresh_token") directly into Credentials(...). After the first successful Google callback, calendar refresh/sync will start using encrypted strings and fail. Please land the matching decrypt-on-read change before shipping this write path.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.
In `@backend/routes/auth.py` around lines 225 - 230, The calendar token reader
must decrypt persisted ciphertext before building the Credentials object: update
the code that constructs Credentials(...) in backend/routes/calendar.py (where
it currently passes token_row["access_token"] and
token_row.get("refresh_token")) to call decrypt on access_token and
decrypt_if_present on refresh_token (or handle None/empty), and convert the
stored expires_at ISO string back to a datetime for expiry; ensure the same
decrypt helper used for encrypt_if_present is referenced so refresh/decode works
after the Google callback writes encrypted tokens.

[AndresL230]

Summary

Adds AES-256-GCM column-level encryption for user PII, OAuth tokens, assignment notes/points, document summaries/concept notes, session summaries, and chat messages. Includes encrypt-on-write + decrypt-on-read across all affected routes, a schema migration that retypes encrypted columns to TEXT, and an idempotent backfill script for existing rows.

Rollout — three things you need to do

1. What to apply to Supabase

Run one SQL file in the Supabase SQL editor: backend/db/migration_encryption_text_columns.sql. It contains four ALTER TABLE ... ALTER COLUMN ... TYPE TEXT USING ::TEXT statements.

Apply it once, before deploying the new code. The casts preserve existing rows as TEXT (e.g., 87.5 becomes the string "87.5"); the decrypt_if_present / decrypt_numeric fallbacks keep those legacy rows readable until you backfill.

2. Values you need to set

Just one new env var. ENCRYPTION_KEY = 64 hex chars (32 bytes). Generate it with:

python -c "import secrets; print(secrets.token_hex(32))"

Set it in:

• backend/.env for local dev (backend/.env.example already has the placeholder + the generation command).
• Wherever your backend actually runs in deploy (Cloudflare Workers/Pages env vars, Vercel, Fly, Railway, whatever — the same place SUPABASE_SERVICE_KEY is set today). docker-compose.yml already passes it through from backend/.env.

Two non-negotiables:

• The same key must be used everywhere your backend runs. Different keys = ciphertext written by one instance is unreadable by another.
• Never rotate or lose this key. Losing it permanently bricks every encrypted column. If you need to rotate, write a script that decrypts with the old key and re-encrypts with the new one in one transaction.

The backend will refuse to boot if ENCRYPTION_KEY is missing, not 64 chars, or not valid hex (intentional fail-fast).

3. The backfill script

backend/db/backfill_encryption.py. For each encrypted column on each table (users.name/email/bio/..., oauth_tokens.access_token/refresh_token, assignments.notes/points_*, documents.summary/concept_notes, sessions.summary_json, messages.content, room_messages.text), it:

1. Selects every row.
2. For each cell, calls decrypt(value) once.
3. If it succeeds → already encrypted → skip.
4. If it raises → the cell is still legacy plaintext → encrypt it and write back.

Prints counts per column. Idempotent — running it a second time changes nothing. Defaults to dry-run (counts only); --apply to actually write. --table users to do it in stages.

How to actually run all of this, in order

# 1. Generate and set the key
python -c "import secrets; print(secrets.token_hex(32))"# paste output as ENCRYPTION_KEY=... in backend/.env# AND set the same value in your deploy environment# 2. Apply the schema migration in Supabase# Dashboard → SQL Editor → paste contents of:# backend/db/migration_encryption_text_columns.sql → Run# 3. Deploy the new backend code (encryption wiring is on this branch)# 4. Backfill — first dry-run to see what will change:cd backend
.\venv\Scripts\python.exe -m db.backfill_encryption
# 5. Then actually apply:
.\venv\Scripts\python.exe -m db.backfill_encryption --apply

After the backfill completes successfully, the decrypt_if_present fallback-to-raw-value warnings should stop appearing in logs. That's the signal it worked.

Test plan

• Apply migration_encryption_text_columns.sql to a Supabase branch DB
• Set ENCRYPTION_KEY (64-hex) and confirm backend boots; confirm it refuses to boot when the var is missing/invalid
• Run backend tests: cd backend && python -m pytest tests/ -q (includes new test_encryption.py)
• Sign in via Google OAuth → confirm users.name/email written as ciphertext, /me returns plaintext
• Upload a document → confirm documents.summary/concept_notes ciphertext at rest, decrypt on library/study-guide/flashcards reads
• Sync calendar → confirm oauth_tokens.access_token/refresh_token and assignments.notes/points_* encrypted
• Send a room message + a learn-session message → confirm room_messages.text and messages.content encrypted
• Run backfill in dry-run on a copy of prod data, verify counts, then --apply and re-run to confirm idempotency (zero changes)
• Confirm decrypt_if_present fallback warnings disappear from logs after backfill

Summary by CodeRabbit

• New Features

  • End-to-end encryption for sensitive data (profiles, documents, sessions, messages, tokens).

• Improvements

  • Decryption in responses and encryption on save for many user-facing flows.
  • Tighter per-request authorization across endpoints and stricter ownership checks.

• Chores

  • Added encryption key configuration and dependency updates; adjusted schema to support encrypted values.

• Tests & Docs

  • Added encryption test coverage and an implementation/rollout plan.

[cloudflare-workers-and-pages]

Deploying with Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Preview URL	Updated (UTC)
✅ Deployment successful! View logs	frontend	43d9015	Commit Preview URL Branch Preview URL	May 03 2026, 07:57 PM

[coderabbitai]

📝 Walkthrough

Walkthrough

Adds AES-256-GCM column-level encryption: new encryption service, test coverage, env/docker wiring, a migration to TEXT for certain columns, a one-shot backfill CLI, and pervasive route changes to encrypt sensitive writes, decrypt reads, and enforce request-based authorization.

Changes

Encryption rollout & route wiring

Layer / File(s)	Summary
Data Shape / Schema Prep backend/db/migration_encryption_text_columns.sql	Retypes specific numeric/JSONB columns to TEXT using USING <col>::TEXT to allow storing ciphertext strings.
Dependencies backend/requirements.txt	Pins cryptography (>=42,<46).
Environment backend/.env.example, docker-compose.yml	Adds ENCRYPTION_KEY placeholder and passes ${ENCRYPTION_KEY} into the backend service.
Encryption Core backend/services/encryption.py	New AES-256-GCM helpers: key loader/validation, encrypt/decrypt, encrypt_if_present/decrypt_if_present, decrypt_numeric, encrypt_json/decrypt_json.
Backfill Tool backend/db/backfill_encryption.py	One-shot CLI that scans configured tables/columns, detects already-encrypted vs legacy plaintext/JSON/numeric values, and optionally writes encrypted values with --apply.
Auth Guard Tightening backend/services/auth_guard.py	get_session_user_id now requires a valid session token (no query-param fallback) and raises 401 on missing/invalid payload.
Route Integration (reads/writes & auth) backend/routes/*.py (auth, onboarding, profile, admin, social, quiz, learn, calendar, gradebook, documents, flashcards, study_guide, graph)	Handlers now accept Request where applicable, enforce require_self/session ownership, encrypt sensitive fields on write and decrypt on read, and narrow SELECT projections. OAuth tokens are decrypted for use and encrypted on refresh/storage. Several patch/allowlist behaviors adjusted to exclude sensitive fields.
Frontend adjustments frontend/src/app/auth/callback/page.tsx, frontend/src/app/api/auth/session/route.ts, frontend/src/middleware.ts	Auth callback no longer requires name param and fetches /api/auth/me from session; session route now requires/verifies authToken; middleware forwards sapling_session cookie to backend auth check.
Tests & Test Setup backend/tests/conftest.py, backend/tests/test_encryption.py, backend/tests/*	Deterministic test key in env, autouse fixture bypasses session auth for route tests, new encryption unit tests (string/JSON/numeric/nonce/tamper), and multiple route test updates to accommodate request-based auth and encrypted fields.
Docs / Plan docs/superpowers/plans/2026-05-03-aes-256-gcm-column-encryption.md	Comprehensive rollout plan, inventory of # ENCRYPTED LATER markers, migration/backfill instructions, and follow-up tasks.

Sequence Diagram

sequenceDiagram
participant Client
participant RouteHandler
participant AuthGuard
participant EncryptionSvc
participant Database
rect rgba(100, 150, 200, 0.5)
Note over Client,Database: Write path (encrypt before persist)
Client->>RouteHandler: POST /api/... (user_id, sensitive)
RouteHandler->>AuthGuard: require_self(user_id, request)
AuthGuard-->>RouteHandler: authorized
RouteHandler->>EncryptionSvc: encrypt(sensitive)
EncryptionSvc-->>RouteHandler: ciphertext
RouteHandler->>Database: INSERT/UPDATE (ciphertext)
Database-->>RouteHandler: OK
RouteHandler-->>Client: 200 (response with decrypted fields)
end
rect rgba(150, 200, 100, 0.5)
Note over Client,Database: Read path (decrypt on load)
Client->>RouteHandler: GET /api/.../{user_id}
RouteHandler->>AuthGuard: require_self(user_id, request)
AuthGuard-->>RouteHandler: authorized
RouteHandler->>Database: SELECT (ciphertext_field)
Database-->>RouteHandler: row with ciphertext
RouteHandler->>EncryptionSvc: decrypt_if_present(ciphertext)
EncryptionSvc-->>RouteHandler: plaintext or legacy value
RouteHandler-->>Client: 200 (plaintext)
end
rect rgba(200, 100, 100, 0.5)
Note over RouteHandler,EncryptionSvc: Legacy plaintext fallback
RouteHandler->>EncryptionSvc: decrypt_if_present(legacy_plaintext)
EncryptionSvc-->>RouteHandler: returns original plaintext (logs warning)
end

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Possibly related PRs

• adding approval gate for closed beta #56: Overlaps changes to backend/routes/auth.py GET /me (authorization and returned fields).
• Course ID schema migration + calendar assignment normalization #53: Overlaps calendar assignment flows and OAuth token handling in backend/routes/calendar.py.
• Frontend revamp (M1-M9 + deferred items + production hardening) #62: Related frontend session handling changes to frontend/src/app/api/auth/session/route.ts (cookie/session verification).

Poem

🐰
I hopped through code at dawn's first light,
Wrapped secrets snug in AES so tight,
Nonces fresh, each byte takes flight,
Now data sleeps secure each night.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 16.56% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'feat: AES-256-GCM column-level encryption for user PII' directly and clearly summarizes the main feature being added—column-level encryption for sensitive user data.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description check	✅ Passed	The PR description comprehensively covers what the PR does, why, rollout steps, environment configuration, backfill instructions, and test plan—all aligned with the description template structure.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/aes-256-gcm-encryption

Tip

💬 Introducing Slack Agent: The best way for teams to turn conversations into code.

Slack Agent is built on CodeRabbit's deep understanding of your code, so your team can collaborate across the entire SDLC without losing context.

• Generate code and open pull requests
• Plan features and break down work
• Investigate incidents and troubleshoot customer tickets together
• Automate recurring tasks and respond to alerts with triggers
• Summarize progress and report instantly

Built for teams:

• Shared memory across your entire org—no repeating context
• Per-thread sandboxes to safely plan and execute work
• Governance built-in—scoped access, auditability, and budget controls

One agent for your entire SDLC. Right inside Slack.

👉 Get started

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 4

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (4)

backend/routes/quiz.py (1)

190-203: ⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Guard student_name against nulls before template replacement.

decrypt_if_present() can return None. If users.name is null, the .replace("{student_name}", student_name) call raises TypeError after the quiz attempt and mastery updates have already been persisted.

Suggested fix

- student_name = decrypt_if_present(user_rows[0]["name"]) if user_rows else "Student"+ student_name = (+ decrypt_if_present(user_rows[0].get("name")) or "Student"+ if user_rows+ else "Student"+ )

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.
In `@backend/routes/quiz.py` around lines 190 - 203, The student_name value used
in the prompt can be None because decrypt_if_present(user_rows[0]["name"]) may
return None; before calling .replace("{student_name}", student_name) ensure
student_name is a non-null string (e.g., coerce to a fallback like "Student" or
"" if None) so template replacement never receives None; update the code around
where student_name is assigned (the decrypt_if_present call and subsequent use
in ctx_prompt/_load_prompt) to coerce or default the value and use that
sanitized variable in the .replace call.

backend/routes/gradebook.py (1)

242-255: ⚠️ Potential issue | 🟠 Major | ⚡ Quick win

Return decrypted fields from create_assignment().

This route now writes encrypted points_possible, points_earned, and notes, then returns inserted[0] verbatim. Any client that uses the POST response to update local state will receive ciphertext instead of the values it just submitted, while the read endpoints return plaintext.

Suggested fix

 inserted = table("assignments").insert({
"id": new_id,
"user_id": body.user_id,
"course_id": body.course_id,
"title": body.title,
"category_id": body.category_id,
"points_possible": encrypt_if_present(body.points_possible),
"points_earned": encrypt_if_present(body.points_earned),
"due_date": body.due_date,
"assignment_type": body.assignment_type,
"notes": encrypt_if_present(body.notes),
"source": "manual",
})
- return {"assignment": inserted[0] if inserted else None}+ assignment = inserted[0] if inserted else None+ if assignment:+ assignment["points_possible"] = decrypt_numeric(assignment.get("points_possible"))+ assignment["points_earned"] = decrypt_numeric(assignment.get("points_earned"))+ assignment["notes"] = decrypt_if_present(assignment.get("notes"))+ return {"assignment": assignment}

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.
In `@backend/routes/gradebook.py` around lines 242 - 255, The POST handler
currently inserts encrypted values (using encrypt_if_present) and returns
inserted[0] as-is, causing ciphertext to be returned; after the insert in
create_assignment (the block that builds inserted =
table("assignments").insert(...)), decrypt the stored fields before returning by
running points_possible, points_earned, and notes through the corresponding
decrypt helper (e.g., decrypt_if_present) and then return the modified
assignment object (rather than the raw inserted[0]); update the return to return
{"assignment": decrypted_assignment} so clients receive plaintext fields
consistent with read endpoints.

backend/routes/learn.py (1)

525-532: ⚠️ Potential issue | 🟠 Major | ⚡ Quick win

Messages returned by resume_session are not decrypted.

When resuming a persisted session, the messages fetched from the database have encrypted content but are returned directly without decryption. This is inconsistent with get_conversation_history which decrypts message content.

🐛 Proposed fix

 msgs = table("messages").select(
"id,role,content,created_at",
filters={"session_id": f"eq.{session_id}"},
order="created_at.asc",
)
+ for m in msgs:+ m["content"] = decrypt_if_present(m.get("content"))
return {
"session": session_rows[0],
"messages": msgs,
}

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.
In `@backend/routes/learn.py` around lines 525 - 532, The messages returned by
resume_session are fetched into msgs via table("messages").select but not
decrypted; update resume_session to reuse the decryption logic from
get_conversation_history (or call get_conversation_history(session_id) instead
of returning raw msgs) so each message's content is decrypted before returning.
Locate the msgs variable and the return that currently returns session_rows[0]
and msgs, then either map over msgs and replace each message's content with the
decrypted value using the same helper used by get_conversation_history, or
delegate to get_conversation_history to produce the decrypted messages, and
return that result.

backend/routes/social.py (1)

343-371: ⚠️ Potential issue | 🟠 Major

user_name is stored unencrypted in room_messages.

The message text is encrypted but body.user_name is stored in plaintext. This is inconsistent with the PR's goal of encrypting PII. User names are PII and should be encrypted at rest.

This also requires updating get_room_messages to decrypt user_name in the message rows (line 290) and reply snippets (line 320).

🔒 Proposed fix to encrypt user_name

 row = table("room_messages").insert({
"room_id": room_id,
"user_id": body.user_id,
- "user_name": body.user_name,+ "user_name": encrypt_if_present(body.user_name),
"text": encrypt_if_present(body.text or None),
"image_url": body.image_url or None,
"reply_to_id": body.reply_to_id or None,
})
if row:
row[0]["text"] = decrypt_if_present(row[0].get("text"))
+ row[0]["user_name"] = decrypt_if_present(row[0].get("user_name"))

In get_room_messages, decrypt user_name when retrieving message rows and reply snippets.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.
In `@backend/routes/social.py` around lines 343 - 371, send_room_message currently
stores body.user_name in plaintext; update the insert in send_room_message to
pass user_name through encrypt_if_present (same pattern as text) so user_name is
encrypted at rest. Then update get_room_messages to call decrypt_if_present on
the message row's user_name and also on any reply snippet user_name (the
reply_to handling at/around where reply snippets are built) to return decrypted
names to clients; preserve null/None handling consistent with
encrypt_if_present/decrypt_if_present usage.

🧹 Nitpick comments (8)

backend/services/auth_guard.py (1)

60-61: 💤 Low value

Add exception chaining for better error tracing.

While catching a broad Exception is acceptable here (any decode failure should yield 401), using raise ... from would preserve the original exception context for debugging.

♻️ Suggested improvement

- except Exception:- raise HTTPException(status_code=401, detail="Not authenticated")+ except Exception as exc:+ raise HTTPException(status_code=401, detail="Not authenticated") from exc

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.
In `@backend/services/auth_guard.py` around lines 60 - 61, The except block
currently swallows the original exception; update the handler in auth_guard.py
so the broad except Exception captures the original exception (e.g., except
Exception as e:) and re-raise the HTTPException with exception chaining (raise
HTTPException(status_code=401, detail="Not authenticated") from e) to preserve
the original traceback for debugging while still returning 401 from the
authentication function/handler.

backend/routes/onboarding.py (1)

14-14: 💤 Low value

Unused request parameter in search_courses.

The request: Request parameter is accepted but never used in this function. If this is intentional for consistency or future auth guards, consider adding a comment. Otherwise, remove it to avoid confusion.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.
In `@backend/routes/onboarding.py` at line 14, The function search_courses
currently declares an unused parameter request: Request which causes confusion;
either remove the request parameter from the function signature of
search_courses (and any corresponding route decorator/handler registration) or,
if it's intentionally reserved for future use (e.g., auth or middleware), add an
inline comment above the signature explaining why request is unused (e.g., "#
request kept for future auth guard") and prefix the variable with an underscore
(request -> _request) to signal intentional non-use. Update any callers or route
mappings that expect the old signature accordingly and ensure imports (Request)
are cleaned up if removed.

backend/db/backfill_encryption.py (2)

91-91: 🏗️ Heavy lift

No pagination — large tables may cause memory/timeout issues.

table(table_name).select(...) on line 91 (and similar calls) loads all rows into memory. For tables with millions of rows (e.g., messages, room_messages), this could exhaust memory or timeout.

Consider adding batching with limit and offset, or using cursor-based pagination:

Example batch approach

BATCH_SIZE=1000offset=0whileTrue:
rows=table(table_name).select(
",".join([pk, *columns]),
limit=BATCH_SIZE,
offset=offset,
order=f"{pk}.asc"
) or []
ifnotrows:
break# process rows...offset+=BATCH_SIZE

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.
In `@backend/db/backfill_encryption.py` at line 91, The current call rows =
table(table_name).select(",".join([pk, *columns])) loads the entire table into
memory; change the logic around table(table_name).select to iterate in batches
(use limit/offset or a cursor) while selecting the same columns (referencing
table_name, pk, columns and the table(...) call) so you fetch e.g. BATCH_SIZE
rows at a time, process them, then advance the offset (or cursor) and repeat
until no rows remain; ensure you preserve ordering (order by pk) to make
pagination deterministic and avoid loading all rows into memory.

---

162-172: 💤 Low value

Corrupt JSON encrypted as raw string may cause decrypt mismatch.

When JSON parsing fails (line 164), the raw string is encrypted via encrypt(v) (line 169). However, reads use decrypt_json() which expects json.loads(decrypt(value)). Decrypting will succeed, but json.loads will fail on the corrupt JSON, triggering the fallback path.

This is acceptable since the fallback handles it, but documenting this behavior would help future maintainers understand why some cells fail JSON parsing after decryption.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.
In `@backend/db/backfill_encryption.py` around lines 162 - 172, When JSON parsing
fails in backfill_encryption.py (the _json.loads(v) exception path), we
currently encrypt the raw string with encrypt(v) so the value can round-trip
through decrypt_if_present/decrypt_json(); add a clear inline comment near the
except block explaining that decrypt_json() will call json.loads(decrypt(value))
and therefore decrypted corrupt JSON will re-trigger the JSON parse fallback at
read time, and that this is intentional because the runtime fallback will handle
it; reference the functions _json.loads, encrypt, decrypt_json, and
decrypt_if_present in the comment so future maintainers understand the
round-trip behavior and why some cells may still fail JSON parsing after
decryption.

frontend/src/app/auth/callback/page.tsx (1)

70-77: 💤 Low value

Silent failure fallback masks /api/auth/me errors.

When the /api/auth/me fetch fails (line 75), the code defaults onboardingCompleted = true, which could incorrectly skip onboarding for users who haven't completed it if the API is temporarily unavailable. Consider logging this case or retrying.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.
In `@frontend/src/app/auth/callback/page.tsx` around lines 70 - 77, The catch
block for the fetch('/api/auth/me') call in page.tsx silently sets
onboardingCompleted = true which can incorrectly skip onboarding on transient
API failures; update the catch to capture the error (e.g., catch (err)), log it
(console.error or your app logger) and set onboardingCompleted conservatively
(false or leave undefined) or implement a simple retry before deciding,
referencing the fetch('/api/auth/me') call and the onboardingCompleted/local
state update to locate the fix.

backend/routes/flashcards.py (1)

128-137: 💤 Low value

Silent pass on decrypt failure is acceptable but consider logging.

The try-except-pass on lines 133-136 silently ignores decryption failures for concept_notes. While this is intentional for legacy plaintext compatibility, the encryption module's docstring mentions "fallback logs a warning." Consider adding a logging statement here for consistency with the stated rollout observability.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.
In `@backend/routes/flashcards.py` around lines 128 - 137, The code silently
swallows exceptions when calling decrypt_json on d.get("concept_notes"); instead
add a warning log inside the except to surface the failure (include context like
the doc id/index and use exc_info=True or log the exception message) while
preserving the fallback behavior of leaving concept_notes unchanged; reference
the decrypt_json call and d["concept_notes"], and ensure you use the module
logger (e.g., obtain logging.getLogger(__name__) or reuse an existing logger
variable) before logging.

backend/routes/learn.py (1)

231-239: ⚡ Quick win

Use explicit None union type annotation.

PEP 484 prohibits implicit Optional. The type hint should use | None for clarity.

♻️ Proposed fix

-def save_message(session_id: str, role: str, content: str, graph_update: dict = None):+def save_message(session_id: str, role: str, content: str, graph_update: dict | None = None):

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.
In `@backend/routes/learn.py` around lines 231 - 239, Update the function
signature for save_message to use an explicit None union type for the
graph_update parameter: replace the implicit Optional style "graph_update: dict
= None" with the explicit union form "graph_update: dict | None = None"
(referencing the save_message function and the graph_update parameter) so the
type hint conforms to PEP 484; ensure no other code changes are required.

backend/tests/test_encryption.py (1)

99-106: Use specific exception type for tamper detection test.

The test currently catches Exception, which is too broad. AES-GCM tamper detection raises cryptography.exceptions.InvalidTag, and using the specific exception type makes the test more precise and prevents accidentally passing if a different exception is raised.

♻️ Proposed fix

 def test_tampered_ciphertext_raises():
import base64
+ from cryptography.exceptions import InvalidTag
ct = encryption.encrypt("secret")
raw = bytearray(base64.b64decode(ct))
raw[-1] ^= 0x01 # flip one bit in the tag
tampered = base64.b64encode(bytes(raw)).decode()
- with pytest.raises(Exception):+ with pytest.raises(InvalidTag):
encryption.decrypt(tampered)

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.
In `@backend/tests/test_encryption.py` around lines 99 - 106, The test
test_tampered_ciphertext_raises should assert the specific AES-GCM tamper
exception instead of catching all Exceptions: import InvalidTag from
cryptography.exceptions and change the context manager to with
pytest.raises(InvalidTag): calling encryption.decrypt(tampered). Keep the rest
of the test (encryption.encrypt and bit-flip tampering) unchanged so it still
exercises tamper detection.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@backend/db/migration_encryption_text_columns.sql`:
- Around line 13-27: The migration casts documents.concept_notes and
sessions.summary_json to TEXT but services/encryption.py's decrypt_json() lacks
the legacy-plaintext fallback, so pre-backfill rows will break; update
decrypt_json() (in backend/services/encryption.py) to detect and return
plaintext JSON when input isn't valid ciphertext (similar to the scalar
fallbacks used by decrypt_text()/decrypt_number()), or alternatively ensure the
DB backfill and enabling of readers are performed atomically so decrypt_json()
never sees legacy plaintext—modify either decrypt_json() to include a JSON
fallback helper or adjust the deployment/migration process to run the backfill
before enabling readers for documents.concept_notes and sessions.summary_json.
In `@backend/routes/auth.py`:
- Around line 228-229: The code is encrypting an empty string when
creds.refresh_token is None (calling encrypt("")), causing inconsistent handling
vs backfilled rows; change the assignment that sets "refresh_token" to either
call encrypt_if_present(creds.refresh_token) or keep a None value when
creds.refresh_token is falsy so empty strings are not encrypted—update the
object construction where "refresh_token" is set (referencing encrypt and
creds.refresh_token) to use encrypt_if_present or conditional preservation of
None to match the backfill behavior.
In `@backend/services/encryption.py`:
- Around line 116-117: decrypt_json currently assumes input is encrypted and
will raise if passed legacy plaintext JSON; update decrypt_json to mirror
decrypt_if_present by attempting to decrypt then json.loads, but on decryption
failure (or if decrypted result is invalid) fall back to json.loads(value) so
pre-encryption JSON still parses; locate the decrypt_json function and wrap its
call to decrypt(value) in a try/except (or check the decrypt result) and use
json.loads(value) as the fallback.
In `@backend/tests/conftest.py`:
- Around line 32-69: The current fixture only monkeypatches already-imported
route modules, leaving services.auth_guard itself untouched and causing
import-order dependent behavior; update the fixture to also monkeypatch the
functions on the services.auth_guard module (replace auth_guard._decode_session
with _decode_session_stub and auth_guard.get_session_user_id,
auth_guard.require_self, auth_guard.require_admin, and auth_guard.require_role
with the corresponding stubs/_require_role_stub) so any later-imported routes
that reference auth_guard will get the bypassed implementations; keep the
existing stubs (_decode_session_stub, _get_session_user_id_stub,
_require_self_stub, _require_admin_stub, _require_role_stub) and use
monkeypatch.setattr(auth_guard, "<name>", <stub>) for each symbol.
---
Outside diff comments:
In `@backend/routes/gradebook.py`:
- Around line 242-255: The POST handler currently inserts encrypted values
(using encrypt_if_present) and returns inserted[0] as-is, causing ciphertext to
be returned; after the insert in create_assignment (the block that builds
inserted = table("assignments").insert(...)), decrypt the stored fields before
returning by running points_possible, points_earned, and notes through the
corresponding decrypt helper (e.g., decrypt_if_present) and then return the
modified assignment object (rather than the raw inserted[0]); update the return
to return {"assignment": decrypted_assignment} so clients receive plaintext
fields consistent with read endpoints.
In `@backend/routes/learn.py`:
- Around line 525-532: The messages returned by resume_session are fetched into
msgs via table("messages").select but not decrypted; update resume_session to
reuse the decryption logic from get_conversation_history (or call
get_conversation_history(session_id) instead of returning raw msgs) so each
message's content is decrypted before returning. Locate the msgs variable and
the return that currently returns session_rows[0] and msgs, then either map over
msgs and replace each message's content with the decrypted value using the same
helper used by get_conversation_history, or delegate to get_conversation_history
to produce the decrypted messages, and return that result.
In `@backend/routes/quiz.py`:
- Around line 190-203: The student_name value used in the prompt can be None
because decrypt_if_present(user_rows[0]["name"]) may return None; before calling
.replace("{student_name}", student_name) ensure student_name is a non-null
string (e.g., coerce to a fallback like "Student" or "" if None) so template
replacement never receives None; update the code around where student_name is
assigned (the decrypt_if_present call and subsequent use in
ctx_prompt/_load_prompt) to coerce or default the value and use that sanitized
variable in the .replace call.
In `@backend/routes/social.py`:
- Around line 343-371: send_room_message currently stores body.user_name in
plaintext; update the insert in send_room_message to pass user_name through
encrypt_if_present (same pattern as text) so user_name is encrypted at rest.
Then update get_room_messages to call decrypt_if_present on the message row's
user_name and also on any reply snippet user_name (the reply_to handling
at/around where reply snippets are built) to return decrypted names to clients;
preserve null/None handling consistent with
encrypt_if_present/decrypt_if_present usage.
---
Nitpick comments:
In `@backend/db/backfill_encryption.py`:
- Line 91: The current call rows = table(table_name).select(",".join([pk,
*columns])) loads the entire table into memory; change the logic around
table(table_name).select to iterate in batches (use limit/offset or a cursor)
while selecting the same columns (referencing table_name, pk, columns and the
table(...) call) so you fetch e.g. BATCH_SIZE rows at a time, process them, then
advance the offset (or cursor) and repeat until no rows remain; ensure you
preserve ordering (order by pk) to make pagination deterministic and avoid
loading all rows into memory.
- Around line 162-172: When JSON parsing fails in backfill_encryption.py (the
_json.loads(v) exception path), we currently encrypt the raw string with
encrypt(v) so the value can round-trip through
decrypt_if_present/decrypt_json(); add a clear inline comment near the except
block explaining that decrypt_json() will call json.loads(decrypt(value)) and
therefore decrypted corrupt JSON will re-trigger the JSON parse fallback at read
time, and that this is intentional because the runtime fallback will handle it;
reference the functions _json.loads, encrypt, decrypt_json, and
decrypt_if_present in the comment so future maintainers understand the
round-trip behavior and why some cells may still fail JSON parsing after
decryption.
In `@backend/routes/flashcards.py`:
- Around line 128-137: The code silently swallows exceptions when calling
decrypt_json on d.get("concept_notes"); instead add a warning log inside the
except to surface the failure (include context like the doc id/index and use
exc_info=True or log the exception message) while preserving the fallback
behavior of leaving concept_notes unchanged; reference the decrypt_json call and
d["concept_notes"], and ensure you use the module logger (e.g., obtain
logging.getLogger(__name__) or reuse an existing logger variable) before
logging.
In `@backend/routes/learn.py`:
- Around line 231-239: Update the function signature for save_message to use an
explicit None union type for the graph_update parameter: replace the implicit
Optional style "graph_update: dict = None" with the explicit union form
"graph_update: dict | None = None" (referencing the save_message function and
the graph_update parameter) so the type hint conforms to PEP 484; ensure no
other code changes are required.
In `@backend/routes/onboarding.py`:
- Line 14: The function search_courses currently declares an unused parameter
request: Request which causes confusion; either remove the request parameter
from the function signature of search_courses (and any corresponding route
decorator/handler registration) or, if it's intentionally reserved for future
use (e.g., auth or middleware), add an inline comment above the signature
explaining why request is unused (e.g., "# request kept for future auth guard")
and prefix the variable with an underscore (request -> _request) to signal
intentional non-use. Update any callers or route mappings that expect the old
signature accordingly and ensure imports (Request) are cleaned up if removed.
In `@backend/services/auth_guard.py`:
- Around line 60-61: The except block currently swallows the original exception;
update the handler in auth_guard.py so the broad except Exception captures the
original exception (e.g., except Exception as e:) and re-raise the HTTPException
with exception chaining (raise HTTPException(status_code=401, detail="Not
authenticated") from e) to preserve the original traceback for debugging while
still returning 401 from the authentication function/handler.
In `@backend/tests/test_encryption.py`:
- Around line 99-106: The test test_tampered_ciphertext_raises should assert the
specific AES-GCM tamper exception instead of catching all Exceptions: import
InvalidTag from cryptography.exceptions and change the context manager to with
pytest.raises(InvalidTag): calling encryption.decrypt(tampered). Keep the rest
of the test (encryption.encrypt and bit-flip tampering) unchanged so it still
exercises tamper detection.
In `@frontend/src/app/auth/callback/page.tsx`:
- Around line 70-77: The catch block for the fetch('/api/auth/me') call in
page.tsx silently sets onboardingCompleted = true which can incorrectly skip
onboarding on transient API failures; update the catch to capture the error
(e.g., catch (err)), log it (console.error or your app logger) and set
onboardingCompleted conservatively (false or leave undefined) or implement a
simple retry before deciding, referencing the fetch('/api/auth/me') call and the
onboardingCompleted/local state update to locate the fix.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 0c1bef18-e8e8-4608-9891-9e17ab2b8476

📥 Commits

Reviewing files that changed from the base of the PR and between 1d184ef and ba27384.

📒 Files selected for processing (29)

• backend/.env.example
• backend/db/backfill_encryption.py
• backend/db/migration_encryption_text_columns.sql
• backend/requirements.txt
• backend/routes/admin.py
• backend/routes/auth.py
• backend/routes/calendar.py
• backend/routes/documents.py
• backend/routes/flashcards.py
• backend/routes/gradebook.py
• backend/routes/graph.py
• backend/routes/learn.py
• backend/routes/onboarding.py
• backend/routes/profile.py
• backend/routes/quiz.py
• backend/routes/social.py
• backend/routes/study_guide.py
• backend/services/auth_guard.py
• backend/services/encryption.py
• backend/tests/conftest.py
• backend/tests/test_encryption.py
• backend/tests/test_flashcard_import_routes.py
• backend/tests/test_learn_routes.py
• backend/tests/test_onboarding_routes.py
• backend/tests/test_shared_course_context.py
• backend/tests/test_social_messages.py
• docker-compose.yml
• docs/superpowers/plans/2026-05-03-aes-256-gcm-column-encryption.md
• frontend/src/app/auth/callback/page.tsx

[AndresL230]

Code review

Found 2 issues:

1. resume_session returns encrypted messages.content to the client without decrypting. save_message now writes encrypt_if_present(content) and get_conversation_history correctly applies decrypt_if_present, but resume_session selects id,role,content,created_at from the messages table and returns the rows as-is — users resuming a session will see base64 ciphertext instead of message text.

Sapling/backend/routes/learn.py

Lines 524 to 533 in ba27384

	msgs=table("messages").select(
	"id,role,content,created_at",
	filters={"session_id": f"eq.{session_id}"},
	order="created_at.asc",
	)
	return {
	"session": session_rows[0],
	"messages": msgs,
	}

2. The /auth/me endpoint signature changed to require a verified session (get_session_user_id(request) — accepts only an auth_token query param or sapling_session cookie), but frontend/src/middleware.ts still calls ${API_URL}/api/auth/me?user_id=... from edge middleware without forwarding either credential. Edge fetch() does not auto-forward browser cookies, so every protected-route navigation will receive 401 Not authenticated and fall into the redirectToSignin(request, 'session_expired') branch — full sign-in regression for approved users. The same ?user_id=... pattern is also used by frontend/src/app/api/auth/session/route.ts (fallback path) and frontend/src/context/UserContext.tsx.

Sapling/frontend/src/middleware.ts

Lines 43 to 62 in ba27384

	if(!API_URL)returnredirectToSignin(request,'google_not_configured')
	try{
	constcontroller=newAbortController()
	consttimeout=setTimeout(()=>controller.abort(),3000)
	letres: Response
	try{
	res=awaitfetch(
	`${API_URL}/api/auth/me?user_id=${encodeURIComponent(session.userId)}`,
	{signal: controller.signal},
	)
	}finally{
	clearTimeout(timeout)
	}
	if(!res.ok)returnredirectToSignin(request,'session_expired')
	constdata=awaitres.json()
	if(data.is_approved!==true)returnNextResponse.redirect(newURL('/pending',request.url))
	}catch{
	returnredirectToSignin(request,'signin_failed')
	}

Sapling/backend/services/auth_guard.py

Lines 16 to 51 in ba27384

	def_decode_session(request: Request) ->dict:
	"""Extract and verify the session token from query params or cookies."""
	token=request.query_params.get("auth_token") orrequest.cookies.get("sapling_session")
	ifnottokenornotSESSION_SECRET:
	raiseHTTPException(status_code=401, detail="Not authenticated")
	parts=token.split(".")
	iflen(parts) !=2:
	raiseHTTPException(status_code=401, detail="Invalid session token")
	payload_b64, sig_b64=parts
	# Verify signature
	expected_sig=_hmac.new(
	SESSION_SECRET.encode(), payload_b64.encode(), hashlib.sha256
	).digest()
	expected_b64=base64.urlsafe_b64encode(expected_sig).decode().rstrip("=")
	ifnot_hmac.compare_digest(sig_b64, expected_b64):
	raiseHTTPException(status_code=401, detail="Invalid session token")
	# Decode payload
	padding=4-len(payload_b64) %4
	ifpadding!=4:
	payload_b64+="="*padding
	try:
	payload=json.loads(base64.urlsafe_b64decode(payload_b64).decode())
	exceptException:
	raiseHTTPException(status_code=401, detail="Invalid session token")
	# Check expiry
	ifpayload.get("exp", 0) <int(_time.time()):
	raiseHTTPException(status_code=401, detail="Session expired")
	returnpayload

🤖 Generated with Claude Code

_{- If this code review was useful, please react with 👍. Otherwise, react with 👎.}

[coderabbitai]

Actionable comments posted: 2

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

frontend/src/app/api/auth/session/route.ts (1)

57-70: ⚠️ Potential issue | 🔴 Critical | 🏗️ Heavy lift

Align the sapling_session payload with backend auth_guard.

This route still mints the browser session through signSession(verifiedUserId), but frontend/src/lib/sessionToken.ts:32-41 signs { userId, exp } while backend/services/auth_guard.py:54-64 looks for payload["user_id"]. After this PR, /api/auth/me and the newly request-authenticated backend routes rely on that cookie, so the frontend will accept the session locally but the backend will 401 it and bounce approved users back to sign-in. Please make both sides read/write the same claim name, ideally with backward-compatible decoding during rollout.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.
In `@frontend/src/app/api/auth/session/route.ts` around lines 57 - 70, The
frontend is signing session tokens with a payload using the claim name userId
while the backend auth_guard expects user_id; update the signer used by
signSession (and the payload created in frontend's sessionToken.ts) to emit {
user_id, exp } instead of { userId, exp } or add backward-compatible decoding in
signSession so it also sets user_id when only userId exists, and ensure
verifyAuthToken/signSession continue to produce the cookie name sapling_session
with the same maxAge settings so backend(routes using auth_guard.py) will accept
the cookie during rollout.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@backend/routes/auth.py`:
- Around line 225-230: The calendar token reader must decrypt persisted
ciphertext before building the Credentials object: update the code that
constructs Credentials(...) in backend/routes/calendar.py (where it currently
passes token_row["access_token"] and token_row.get("refresh_token")) to call
decrypt on access_token and decrypt_if_present on refresh_token (or handle
None/empty), and convert the stored expires_at ISO string back to a datetime for
expiry; ensure the same decrypt helper used for encrypt_if_present is referenced
so refresh/decode works after the Google callback writes encrypted tokens.
---
Outside diff comments:
In `@frontend/src/app/api/auth/session/route.ts`:
- Around line 57-70: The frontend is signing session tokens with a payload using
the claim name userId while the backend auth_guard expects user_id; update the
signer used by signSession (and the payload created in frontend's
sessionToken.ts) to emit { user_id, exp } instead of { userId, exp } or add
backward-compatible decoding in signSession so it also sets user_id when only
userId exists, and ensure verifyAuthToken/signSession continue to produce the
cookie name sapling_session with the same maxAge settings so backend(routes
using auth_guard.py) will accept the cookie during rollout.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 01b8fe9a-7972-4263-9df1-4a7b944fcea4

📥 Commits

Reviewing files that changed from the base of the PR and between ba27384 and 43d9015.

📒 Files selected for processing (9)

• backend/routes/auth.py
• backend/routes/documents.py
• backend/routes/flashcards.py
• backend/routes/learn.py
• backend/services/encryption.py
• backend/tests/conftest.py
• backend/tests/test_flashcard_import_routes.py
• frontend/src/app/api/auth/session/route.ts
• frontend/src/middleware.ts

✅ Files skipped from review due to trivial changes (2)

• backend/tests/test_flashcard_import_routes.py
• backend/tests/conftest.py

[coderabbitai]

⚠️ Potential issue | 🟠 Major | 🏗️ Heavy lift

This will orphan pre-existing accounts that don't already have google_id.

When no google_id match exists, the new path always inserts user_{google_id} with is_approved = False. Any existing approved user created before google_id was populated will end up with a second account and lose access to their original courses, documents, graph, and approval state on next sign-in. This needs a transition strategy before merge, such as a one-time backfill of google_id or a temporary legacy-link path that can still find the old row.

[coderabbitai]

⚠️ Potential issue | 🔴 Critical | ⚡ Quick win

Update the calendar token reader in the same rollout.

These writes now persist ciphertext, but backend/routes/calendar.py:35-71 still passes token_row["access_token"] and token_row.get("refresh_token") directly into Credentials(...). After the first successful Google callback, calendar refresh/sync will start using encrypted strings and fail. Please land the matching decrypt-on-read change before shipping this write path.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.
In `@backend/routes/auth.py` around lines 225 - 230, The calendar token reader
must decrypt persisted ciphertext before building the Credentials object: update
the code that constructs Credentials(...) in backend/routes/calendar.py (where
it currently passes token_row["access_token"] and
token_row.get("refresh_token")) to call decrypt on access_token and
decrypt_if_present on refresh_token (or handle None/empty), and convert the
stored expires_at ISO string back to a datetime for expiry; ensure the same
decrypt helper used for encrypt_if_present is referenced so refresh/decode works
after the Google callback writes encrypted tokens.

[AndresL230]

Summary

Adds AES-256-GCM column-level encryption for user PII, OAuth tokens, assignment notes/points, document summaries/concept notes, session summaries, and chat messages. Includes encrypt-on-write + decrypt-on-read across all affected routes, a schema migration that retypes encrypted columns to TEXT, and an idempotent backfill script for existing rows.

Rollout — three things you need to do

1. What to apply to Supabase

Run one SQL file in the Supabase SQL editor: backend/db/migration_encryption_text_columns.sql. It contains four ALTER TABLE ... ALTER COLUMN ... TYPE TEXT USING ::TEXT statements.

Apply it once, before deploying the new code. The casts preserve existing rows as TEXT (e.g., 87.5 becomes the string "87.5"); the decrypt_if_present / decrypt_numeric fallbacks keep those legacy rows readable until you backfill.

2. Values you need to set

Just one new env var. ENCRYPTION_KEY = 64 hex chars (32 bytes). Generate it with:

python -c "import secrets; print(secrets.token_hex(32))"

Set it in:

• backend/.env for local dev (backend/.env.example already has the placeholder + the generation command).
• Wherever your backend actually runs in deploy (Cloudflare Workers/Pages env vars, Vercel, Fly, Railway, whatever — the same place SUPABASE_SERVICE_KEY is set today). docker-compose.yml already passes it through from backend/.env.

Two non-negotiables:

• The same key must be used everywhere your backend runs. Different keys = ciphertext written by one instance is unreadable by another.
• Never rotate or lose this key. Losing it permanently bricks every encrypted column. If you need to rotate, write a script that decrypts with the old key and re-encrypts with the new one in one transaction.

The backend will refuse to boot if ENCRYPTION_KEY is missing, not 64 chars, or not valid hex (intentional fail-fast).

3. The backfill script

backend/db/backfill_encryption.py. For each encrypted column on each table (users.name/email/bio/..., oauth_tokens.access_token/refresh_token, assignments.notes/points_*, documents.summary/concept_notes, sessions.summary_json, messages.content, room_messages.text), it:

1. Selects every row.
2. For each cell, calls decrypt(value) once.
3. If it succeeds → already encrypted → skip.
4. If it raises → the cell is still legacy plaintext → encrypt it and write back.

Prints counts per column. Idempotent — running it a second time changes nothing. Defaults to dry-run (counts only); --apply to actually write. --table users to do it in stages.

How to actually run all of this, in order

# 1. Generate and set the key
python -c "import secrets; print(secrets.token_hex(32))"# paste output as ENCRYPTION_KEY=... in backend/.env# AND set the same value in your deploy environment# 2. Apply the schema migration in Supabase# Dashboard → SQL Editor → paste contents of:# backend/db/migration_encryption_text_columns.sql → Run# 3. Deploy the new backend code (encryption wiring is on this branch)# 4. Backfill — first dry-run to see what will change:cd backend
.\venv\Scripts\python.exe -m db.backfill_encryption
# 5. Then actually apply:
.\venv\Scripts\python.exe -m db.backfill_encryption --apply

After the backfill completes successfully, the decrypt_if_present fallback-to-raw-value warnings should stop appearing in logs. That's the signal it worked.

Test plan

• Apply migration_encryption_text_columns.sql to a Supabase branch DB
• Set ENCRYPTION_KEY (64-hex) and confirm backend boots; confirm it refuses to boot when the var is missing/invalid
• Run backend tests: cd backend && python -m pytest tests/ -q (includes new test_encryption.py)
• Sign in via Google OAuth → confirm users.name/email written as ciphertext, /me returns plaintext
• Upload a document → confirm documents.summary/concept_notes ciphertext at rest, decrypt on library/study-guide/flashcards reads
• Sync calendar → confirm oauth_tokens.access_token/refresh_token and assignments.notes/points_* encrypted
• Send a room message + a learn-session message → confirm room_messages.text and messages.content encrypted
• Run backfill in dry-run on a copy of prod data, verify counts, then --apply and re-run to confirm idempotency (zero changes)
• Confirm decrypt_if_present fallback warnings disappear from logs after backfill

Summary by CodeRabbit

• New Features

  • End-to-end encryption for sensitive data (profiles, documents, sessions, messages, tokens).

• Improvements

  • Decryption in responses and encryption on save for many user-facing flows.
  • Tighter per-request authorization across endpoints and stricter ownership checks.

• Chores

  • Added encryption key configuration and dependency updates; adjusted schema to support encrypted values.

• Tests & Docs

  • Added encryption test coverage and an implementation/rollout plan.

[cloudflare-workers-and-pages]

Deploying with Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Preview URL	Updated (UTC)
✅ Deployment successful! View logs	frontend	43d9015	Commit Preview URL Branch Preview URL	May 03 2026, 07:57 PM

[coderabbitai]

📝 Walkthrough

Walkthrough

Adds AES-256-GCM column-level encryption: new encryption service, test coverage, env/docker wiring, a migration to TEXT for certain columns, a one-shot backfill CLI, and pervasive route changes to encrypt sensitive writes, decrypt reads, and enforce request-based authorization.

Changes

Encryption rollout & route wiring

Layer / File(s)	Summary
Data Shape / Schema Prep backend/db/migration_encryption_text_columns.sql	Retypes specific numeric/JSONB columns to TEXT using USING <col>::TEXT to allow storing ciphertext strings.
Dependencies backend/requirements.txt	Pins cryptography (>=42,<46).
Environment backend/.env.example, docker-compose.yml	Adds ENCRYPTION_KEY placeholder and passes ${ENCRYPTION_KEY} into the backend service.
Encryption Core backend/services/encryption.py	New AES-256-GCM helpers: key loader/validation, encrypt/decrypt, encrypt_if_present/decrypt_if_present, decrypt_numeric, encrypt_json/decrypt_json.
Backfill Tool backend/db/backfill_encryption.py	One-shot CLI that scans configured tables/columns, detects already-encrypted vs legacy plaintext/JSON/numeric values, and optionally writes encrypted values with --apply.
Auth Guard Tightening backend/services/auth_guard.py	get_session_user_id now requires a valid session token (no query-param fallback) and raises 401 on missing/invalid payload.
Route Integration (reads/writes & auth) backend/routes/*.py (auth, onboarding, profile, admin, social, quiz, learn, calendar, gradebook, documents, flashcards, study_guide, graph)	Handlers now accept Request where applicable, enforce require_self/session ownership, encrypt sensitive fields on write and decrypt on read, and narrow SELECT projections. OAuth tokens are decrypted for use and encrypted on refresh/storage. Several patch/allowlist behaviors adjusted to exclude sensitive fields.
Frontend adjustments frontend/src/app/auth/callback/page.tsx, frontend/src/app/api/auth/session/route.ts, frontend/src/middleware.ts	Auth callback no longer requires name param and fetches /api/auth/me from session; session route now requires/verifies authToken; middleware forwards sapling_session cookie to backend auth check.
Tests & Test Setup backend/tests/conftest.py, backend/tests/test_encryption.py, backend/tests/*	Deterministic test key in env, autouse fixture bypasses session auth for route tests, new encryption unit tests (string/JSON/numeric/nonce/tamper), and multiple route test updates to accommodate request-based auth and encrypted fields.
Docs / Plan docs/superpowers/plans/2026-05-03-aes-256-gcm-column-encryption.md	Comprehensive rollout plan, inventory of # ENCRYPTED LATER markers, migration/backfill instructions, and follow-up tasks.

Sequence Diagram

sequenceDiagram
participant Client
participant RouteHandler
participant AuthGuard
participant EncryptionSvc
participant Database
rect rgba(100, 150, 200, 0.5)
Note over Client,Database: Write path (encrypt before persist)
Client->>RouteHandler: POST /api/... (user_id, sensitive)
RouteHandler->>AuthGuard: require_self(user_id, request)
AuthGuard-->>RouteHandler: authorized
RouteHandler->>EncryptionSvc: encrypt(sensitive)
EncryptionSvc-->>RouteHandler: ciphertext
RouteHandler->>Database: INSERT/UPDATE (ciphertext)
Database-->>RouteHandler: OK
RouteHandler-->>Client: 200 (response with decrypted fields)
end
rect rgba(150, 200, 100, 0.5)
Note over Client,Database: Read path (decrypt on load)
Client->>RouteHandler: GET /api/.../{user_id}
RouteHandler->>AuthGuard: require_self(user_id, request)
AuthGuard-->>RouteHandler: authorized
RouteHandler->>Database: SELECT (ciphertext_field)
Database-->>RouteHandler: row with ciphertext
RouteHandler->>EncryptionSvc: decrypt_if_present(ciphertext)
EncryptionSvc-->>RouteHandler: plaintext or legacy value
RouteHandler-->>Client: 200 (plaintext)
end
rect rgba(200, 100, 100, 0.5)
Note over RouteHandler,EncryptionSvc: Legacy plaintext fallback
RouteHandler->>EncryptionSvc: decrypt_if_present(legacy_plaintext)
EncryptionSvc-->>RouteHandler: returns original plaintext (logs warning)
end

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Possibly related PRs

• adding approval gate for closed beta #56: Overlaps changes to backend/routes/auth.py GET /me (authorization and returned fields).
• Course ID schema migration + calendar assignment normalization #53: Overlaps calendar assignment flows and OAuth token handling in backend/routes/calendar.py.
• Frontend revamp (M1-M9 + deferred items + production hardening) #62: Related frontend session handling changes to frontend/src/app/api/auth/session/route.ts (cookie/session verification).

Poem

🐰
I hopped through code at dawn's first light,
Wrapped secrets snug in AES so tight,
Nonces fresh, each byte takes flight,
Now data sleeps secure each night.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 16.56% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'feat: AES-256-GCM column-level encryption for user PII' directly and clearly summarizes the main feature being added—column-level encryption for sensitive user data.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description check	✅ Passed	The PR description comprehensively covers what the PR does, why, rollout steps, environment configuration, backfill instructions, and test plan—all aligned with the description template structure.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/aes-256-gcm-encryption

Tip

💬 Introducing Slack Agent: The best way for teams to turn conversations into code.

Slack Agent is built on CodeRabbit's deep understanding of your code, so your team can collaborate across the entire SDLC without losing context.

• Generate code and open pull requests
• Plan features and break down work
• Investigate incidents and troubleshoot customer tickets together
• Automate recurring tasks and respond to alerts with triggers
• Summarize progress and report instantly

Built for teams:

• Shared memory across your entire org—no repeating context
• Per-thread sandboxes to safely plan and execute work
• Governance built-in—scoped access, auditability, and budget controls

One agent for your entire SDLC. Right inside Slack.

👉 Get started

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 4

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (4)

backend/routes/quiz.py (1)

190-203: ⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Guard student_name against nulls before template replacement.

decrypt_if_present() can return None. If users.name is null, the .replace("{student_name}", student_name) call raises TypeError after the quiz attempt and mastery updates have already been persisted.

Suggested fix

- student_name = decrypt_if_present(user_rows[0]["name"]) if user_rows else "Student"+ student_name = (+ decrypt_if_present(user_rows[0].get("name")) or "Student"+ if user_rows+ else "Student"+ )

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.
In `@backend/routes/quiz.py` around lines 190 - 203, The student_name value used
in the prompt can be None because decrypt_if_present(user_rows[0]["name"]) may
return None; before calling .replace("{student_name}", student_name) ensure
student_name is a non-null string (e.g., coerce to a fallback like "Student" or
"" if None) so template replacement never receives None; update the code around
where student_name is assigned (the decrypt_if_present call and subsequent use
in ctx_prompt/_load_prompt) to coerce or default the value and use that
sanitized variable in the .replace call.

backend/routes/gradebook.py (1)

242-255: ⚠️ Potential issue | 🟠 Major | ⚡ Quick win

Return decrypted fields from create_assignment().

This route now writes encrypted points_possible, points_earned, and notes, then returns inserted[0] verbatim. Any client that uses the POST response to update local state will receive ciphertext instead of the values it just submitted, while the read endpoints return plaintext.

Suggested fix

 inserted = table("assignments").insert({
"id": new_id,
"user_id": body.user_id,
"course_id": body.course_id,
"title": body.title,
"category_id": body.category_id,
"points_possible": encrypt_if_present(body.points_possible),
"points_earned": encrypt_if_present(body.points_earned),
"due_date": body.due_date,
"assignment_type": body.assignment_type,
"notes": encrypt_if_present(body.notes),
"source": "manual",
})
- return {"assignment": inserted[0] if inserted else None}+ assignment = inserted[0] if inserted else None+ if assignment:+ assignment["points_possible"] = decrypt_numeric(assignment.get("points_possible"))+ assignment["points_earned"] = decrypt_numeric(assignment.get("points_earned"))+ assignment["notes"] = decrypt_if_present(assignment.get("notes"))+ return {"assignment": assignment}

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.
In `@backend/routes/gradebook.py` around lines 242 - 255, The POST handler
currently inserts encrypted values (using encrypt_if_present) and returns
inserted[0] as-is, causing ciphertext to be returned; after the insert in
create_assignment (the block that builds inserted =
table("assignments").insert(...)), decrypt the stored fields before returning by
running points_possible, points_earned, and notes through the corresponding
decrypt helper (e.g., decrypt_if_present) and then return the modified
assignment object (rather than the raw inserted[0]); update the return to return
{"assignment": decrypted_assignment} so clients receive plaintext fields
consistent with read endpoints.

backend/routes/learn.py (1)

525-532: ⚠️ Potential issue | 🟠 Major | ⚡ Quick win

Messages returned by resume_session are not decrypted.

When resuming a persisted session, the messages fetched from the database have encrypted content but are returned directly without decryption. This is inconsistent with get_conversation_history which decrypts message content.

🐛 Proposed fix

 msgs = table("messages").select(
"id,role,content,created_at",
filters={"session_id": f"eq.{session_id}"},
order="created_at.asc",
)
+ for m in msgs:+ m["content"] = decrypt_if_present(m.get("content"))
return {
"session": session_rows[0],
"messages": msgs,
}

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.
In `@backend/routes/learn.py` around lines 525 - 532, The messages returned by
resume_session are fetched into msgs via table("messages").select but not
decrypted; update resume_session to reuse the decryption logic from
get_conversation_history (or call get_conversation_history(session_id) instead
of returning raw msgs) so each message's content is decrypted before returning.
Locate the msgs variable and the return that currently returns session_rows[0]
and msgs, then either map over msgs and replace each message's content with the
decrypted value using the same helper used by get_conversation_history, or
delegate to get_conversation_history to produce the decrypted messages, and
return that result.

backend/routes/social.py (1)

343-371: ⚠️ Potential issue | 🟠 Major

user_name is stored unencrypted in room_messages.

The message text is encrypted but body.user_name is stored in plaintext. This is inconsistent with the PR's goal of encrypting PII. User names are PII and should be encrypted at rest.

This also requires updating get_room_messages to decrypt user_name in the message rows (line 290) and reply snippets (line 320).

🔒 Proposed fix to encrypt user_name

 row = table("room_messages").insert({
"room_id": room_id,
"user_id": body.user_id,
- "user_name": body.user_name,+ "user_name": encrypt_if_present(body.user_name),
"text": encrypt_if_present(body.text or None),
"image_url": body.image_url or None,
"reply_to_id": body.reply_to_id or None,
})
if row:
row[0]["text"] = decrypt_if_present(row[0].get("text"))
+ row[0]["user_name"] = decrypt_if_present(row[0].get("user_name"))

In get_room_messages, decrypt user_name when retrieving message rows and reply snippets.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.
In `@backend/routes/social.py` around lines 343 - 371, send_room_message currently
stores body.user_name in plaintext; update the insert in send_room_message to
pass user_name through encrypt_if_present (same pattern as text) so user_name is
encrypted at rest. Then update get_room_messages to call decrypt_if_present on
the message row's user_name and also on any reply snippet user_name (the
reply_to handling at/around where reply snippets are built) to return decrypted
names to clients; preserve null/None handling consistent with
encrypt_if_present/decrypt_if_present usage.

🧹 Nitpick comments (8)

backend/services/auth_guard.py (1)

60-61: 💤 Low value

Add exception chaining for better error tracing.

While catching a broad Exception is acceptable here (any decode failure should yield 401), using raise ... from would preserve the original exception context for debugging.

♻️ Suggested improvement

- except Exception:- raise HTTPException(status_code=401, detail="Not authenticated")+ except Exception as exc:+ raise HTTPException(status_code=401, detail="Not authenticated") from exc

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.
In `@backend/services/auth_guard.py` around lines 60 - 61, The except block
currently swallows the original exception; update the handler in auth_guard.py
so the broad except Exception captures the original exception (e.g., except
Exception as e:) and re-raise the HTTPException with exception chaining (raise
HTTPException(status_code=401, detail="Not authenticated") from e) to preserve
the original traceback for debugging while still returning 401 from the
authentication function/handler.

backend/routes/onboarding.py (1)

14-14: 💤 Low value

Unused request parameter in search_courses.

The request: Request parameter is accepted but never used in this function. If this is intentional for consistency or future auth guards, consider adding a comment. Otherwise, remove it to avoid confusion.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.
In `@backend/routes/onboarding.py` at line 14, The function search_courses
currently declares an unused parameter request: Request which causes confusion;
either remove the request parameter from the function signature of
search_courses (and any corresponding route decorator/handler registration) or,
if it's intentionally reserved for future use (e.g., auth or middleware), add an
inline comment above the signature explaining why request is unused (e.g., "#
request kept for future auth guard") and prefix the variable with an underscore
(request -> _request) to signal intentional non-use. Update any callers or route
mappings that expect the old signature accordingly and ensure imports (Request)
are cleaned up if removed.

backend/db/backfill_encryption.py (2)

91-91: 🏗️ Heavy lift

No pagination — large tables may cause memory/timeout issues.

table(table_name).select(...) on line 91 (and similar calls) loads all rows into memory. For tables with millions of rows (e.g., messages, room_messages), this could exhaust memory or timeout.

Consider adding batching with limit and offset, or using cursor-based pagination:

Example batch approach

BATCH_SIZE=1000offset=0whileTrue:
rows=table(table_name).select(
",".join([pk, *columns]),
limit=BATCH_SIZE,
offset=offset,
order=f"{pk}.asc"
) or []
ifnotrows:
break# process rows...offset+=BATCH_SIZE

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.
In `@backend/db/backfill_encryption.py` at line 91, The current call rows =
table(table_name).select(",".join([pk, *columns])) loads the entire table into
memory; change the logic around table(table_name).select to iterate in batches
(use limit/offset or a cursor) while selecting the same columns (referencing
table_name, pk, columns and the table(...) call) so you fetch e.g. BATCH_SIZE
rows at a time, process them, then advance the offset (or cursor) and repeat
until no rows remain; ensure you preserve ordering (order by pk) to make
pagination deterministic and avoid loading all rows into memory.

---

162-172: 💤 Low value

Corrupt JSON encrypted as raw string may cause decrypt mismatch.

When JSON parsing fails (line 164), the raw string is encrypted via encrypt(v) (line 169). However, reads use decrypt_json() which expects json.loads(decrypt(value)). Decrypting will succeed, but json.loads will fail on the corrupt JSON, triggering the fallback path.

This is acceptable since the fallback handles it, but documenting this behavior would help future maintainers understand why some cells fail JSON parsing after decryption.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.
In `@backend/db/backfill_encryption.py` around lines 162 - 172, When JSON parsing
fails in backfill_encryption.py (the _json.loads(v) exception path), we
currently encrypt the raw string with encrypt(v) so the value can round-trip
through decrypt_if_present/decrypt_json(); add a clear inline comment near the
except block explaining that decrypt_json() will call json.loads(decrypt(value))
and therefore decrypted corrupt JSON will re-trigger the JSON parse fallback at
read time, and that this is intentional because the runtime fallback will handle
it; reference the functions _json.loads, encrypt, decrypt_json, and
decrypt_if_present in the comment so future maintainers understand the
round-trip behavior and why some cells may still fail JSON parsing after
decryption.

frontend/src/app/auth/callback/page.tsx (1)

70-77: 💤 Low value

Silent failure fallback masks /api/auth/me errors.

When the /api/auth/me fetch fails (line 75), the code defaults onboardingCompleted = true, which could incorrectly skip onboarding for users who haven't completed it if the API is temporarily unavailable. Consider logging this case or retrying.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.
In `@frontend/src/app/auth/callback/page.tsx` around lines 70 - 77, The catch
block for the fetch('/api/auth/me') call in page.tsx silently sets
onboardingCompleted = true which can incorrectly skip onboarding on transient
API failures; update the catch to capture the error (e.g., catch (err)), log it
(console.error or your app logger) and set onboardingCompleted conservatively
(false or leave undefined) or implement a simple retry before deciding,
referencing the fetch('/api/auth/me') call and the onboardingCompleted/local
state update to locate the fix.

backend/routes/flashcards.py (1)

128-137: 💤 Low value

Silent pass on decrypt failure is acceptable but consider logging.

The try-except-pass on lines 133-136 silently ignores decryption failures for concept_notes. While this is intentional for legacy plaintext compatibility, the encryption module's docstring mentions "fallback logs a warning." Consider adding a logging statement here for consistency with the stated rollout observability.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.
In `@backend/routes/flashcards.py` around lines 128 - 137, The code silently
swallows exceptions when calling decrypt_json on d.get("concept_notes"); instead
add a warning log inside the except to surface the failure (include context like
the doc id/index and use exc_info=True or log the exception message) while
preserving the fallback behavior of leaving concept_notes unchanged; reference
the decrypt_json call and d["concept_notes"], and ensure you use the module
logger (e.g., obtain logging.getLogger(__name__) or reuse an existing logger
variable) before logging.

backend/routes/learn.py (1)

231-239: ⚡ Quick win

Use explicit None union type annotation.

PEP 484 prohibits implicit Optional. The type hint should use | None for clarity.

♻️ Proposed fix

-def save_message(session_id: str, role: str, content: str, graph_update: dict = None):+def save_message(session_id: str, role: str, content: str, graph_update: dict | None = None):

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.
In `@backend/routes/learn.py` around lines 231 - 239, Update the function
signature for save_message to use an explicit None union type for the
graph_update parameter: replace the implicit Optional style "graph_update: dict
= None" with the explicit union form "graph_update: dict | None = None"
(referencing the save_message function and the graph_update parameter) so the
type hint conforms to PEP 484; ensure no other code changes are required.

backend/tests/test_encryption.py (1)

99-106: Use specific exception type for tamper detection test.

The test currently catches Exception, which is too broad. AES-GCM tamper detection raises cryptography.exceptions.InvalidTag, and using the specific exception type makes the test more precise and prevents accidentally passing if a different exception is raised.

♻️ Proposed fix

 def test_tampered_ciphertext_raises():
import base64
+ from cryptography.exceptions import InvalidTag
ct = encryption.encrypt("secret")
raw = bytearray(base64.b64decode(ct))
raw[-1] ^= 0x01 # flip one bit in the tag
tampered = base64.b64encode(bytes(raw)).decode()
- with pytest.raises(Exception):+ with pytest.raises(InvalidTag):
encryption.decrypt(tampered)

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.
In `@backend/tests/test_encryption.py` around lines 99 - 106, The test
test_tampered_ciphertext_raises should assert the specific AES-GCM tamper
exception instead of catching all Exceptions: import InvalidTag from
cryptography.exceptions and change the context manager to with
pytest.raises(InvalidTag): calling encryption.decrypt(tampered). Keep the rest
of the test (encryption.encrypt and bit-flip tampering) unchanged so it still
exercises tamper detection.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@backend/db/migration_encryption_text_columns.sql`:
- Around line 13-27: The migration casts documents.concept_notes and
sessions.summary_json to TEXT but services/encryption.py's decrypt_json() lacks
the legacy-plaintext fallback, so pre-backfill rows will break; update
decrypt_json() (in backend/services/encryption.py) to detect and return
plaintext JSON when input isn't valid ciphertext (similar to the scalar
fallbacks used by decrypt_text()/decrypt_number()), or alternatively ensure the
DB backfill and enabling of readers are performed atomically so decrypt_json()
never sees legacy plaintext—modify either decrypt_json() to include a JSON
fallback helper or adjust the deployment/migration process to run the backfill
before enabling readers for documents.concept_notes and sessions.summary_json.
In `@backend/routes/auth.py`:
- Around line 228-229: The code is encrypting an empty string when
creds.refresh_token is None (calling encrypt("")), causing inconsistent handling
vs backfilled rows; change the assignment that sets "refresh_token" to either
call encrypt_if_present(creds.refresh_token) or keep a None value when
creds.refresh_token is falsy so empty strings are not encrypted—update the
object construction where "refresh_token" is set (referencing encrypt and
creds.refresh_token) to use encrypt_if_present or conditional preservation of
None to match the backfill behavior.
In `@backend/services/encryption.py`:
- Around line 116-117: decrypt_json currently assumes input is encrypted and
will raise if passed legacy plaintext JSON; update decrypt_json to mirror
decrypt_if_present by attempting to decrypt then json.loads, but on decryption
failure (or if decrypted result is invalid) fall back to json.loads(value) so
pre-encryption JSON still parses; locate the decrypt_json function and wrap its
call to decrypt(value) in a try/except (or check the decrypt result) and use
json.loads(value) as the fallback.
In `@backend/tests/conftest.py`:
- Around line 32-69: The current fixture only monkeypatches already-imported
route modules, leaving services.auth_guard itself untouched and causing
import-order dependent behavior; update the fixture to also monkeypatch the
functions on the services.auth_guard module (replace auth_guard._decode_session
with _decode_session_stub and auth_guard.get_session_user_id,
auth_guard.require_self, auth_guard.require_admin, and auth_guard.require_role
with the corresponding stubs/_require_role_stub) so any later-imported routes
that reference auth_guard will get the bypassed implementations; keep the
existing stubs (_decode_session_stub, _get_session_user_id_stub,
_require_self_stub, _require_admin_stub, _require_role_stub) and use
monkeypatch.setattr(auth_guard, "<name>", <stub>) for each symbol.
---
Outside diff comments:
In `@backend/routes/gradebook.py`:
- Around line 242-255: The POST handler currently inserts encrypted values
(using encrypt_if_present) and returns inserted[0] as-is, causing ciphertext to
be returned; after the insert in create_assignment (the block that builds
inserted = table("assignments").insert(...)), decrypt the stored fields before
returning by running points_possible, points_earned, and notes through the
corresponding decrypt helper (e.g., decrypt_if_present) and then return the
modified assignment object (rather than the raw inserted[0]); update the return
to return {"assignment": decrypted_assignment} so clients receive plaintext
fields consistent with read endpoints.
In `@backend/routes/learn.py`:
- Around line 525-532: The messages returned by resume_session are fetched into
msgs via table("messages").select but not decrypted; update resume_session to
reuse the decryption logic from get_conversation_history (or call
get_conversation_history(session_id) instead of returning raw msgs) so each
message's content is decrypted before returning. Locate the msgs variable and
the return that currently returns session_rows[0] and msgs, then either map over
msgs and replace each message's content with the decrypted value using the same
helper used by get_conversation_history, or delegate to get_conversation_history
to produce the decrypted messages, and return that result.
In `@backend/routes/quiz.py`:
- Around line 190-203: The student_name value used in the prompt can be None
because decrypt_if_present(user_rows[0]["name"]) may return None; before calling
.replace("{student_name}", student_name) ensure student_name is a non-null
string (e.g., coerce to a fallback like "Student" or "" if None) so template
replacement never receives None; update the code around where student_name is
assigned (the decrypt_if_present call and subsequent use in
ctx_prompt/_load_prompt) to coerce or default the value and use that sanitized
variable in the .replace call.
In `@backend/routes/social.py`:
- Around line 343-371: send_room_message currently stores body.user_name in
plaintext; update the insert in send_room_message to pass user_name through
encrypt_if_present (same pattern as text) so user_name is encrypted at rest.
Then update get_room_messages to call decrypt_if_present on the message row's
user_name and also on any reply snippet user_name (the reply_to handling
at/around where reply snippets are built) to return decrypted names to clients;
preserve null/None handling consistent with
encrypt_if_present/decrypt_if_present usage.
---
Nitpick comments:
In `@backend/db/backfill_encryption.py`:
- Line 91: The current call rows = table(table_name).select(",".join([pk,
*columns])) loads the entire table into memory; change the logic around
table(table_name).select to iterate in batches (use limit/offset or a cursor)
while selecting the same columns (referencing table_name, pk, columns and the
table(...) call) so you fetch e.g. BATCH_SIZE rows at a time, process them, then
advance the offset (or cursor) and repeat until no rows remain; ensure you
preserve ordering (order by pk) to make pagination deterministic and avoid
loading all rows into memory.
- Around line 162-172: When JSON parsing fails in backfill_encryption.py (the
_json.loads(v) exception path), we currently encrypt the raw string with
encrypt(v) so the value can round-trip through
decrypt_if_present/decrypt_json(); add a clear inline comment near the except
block explaining that decrypt_json() will call json.loads(decrypt(value)) and
therefore decrypted corrupt JSON will re-trigger the JSON parse fallback at read
time, and that this is intentional because the runtime fallback will handle it;
reference the functions _json.loads, encrypt, decrypt_json, and
decrypt_if_present in the comment so future maintainers understand the
round-trip behavior and why some cells may still fail JSON parsing after
decryption.
In `@backend/routes/flashcards.py`:
- Around line 128-137: The code silently swallows exceptions when calling
decrypt_json on d.get("concept_notes"); instead add a warning log inside the
except to surface the failure (include context like the doc id/index and use
exc_info=True or log the exception message) while preserving the fallback
behavior of leaving concept_notes unchanged; reference the decrypt_json call and
d["concept_notes"], and ensure you use the module logger (e.g., obtain
logging.getLogger(__name__) or reuse an existing logger variable) before
logging.
In `@backend/routes/learn.py`:
- Around line 231-239: Update the function signature for save_message to use an
explicit None union type for the graph_update parameter: replace the implicit
Optional style "graph_update: dict = None" with the explicit union form
"graph_update: dict | None = None" (referencing the save_message function and
the graph_update parameter) so the type hint conforms to PEP 484; ensure no
other code changes are required.
In `@backend/routes/onboarding.py`:
- Line 14: The function search_courses currently declares an unused parameter
request: Request which causes confusion; either remove the request parameter
from the function signature of search_courses (and any corresponding route
decorator/handler registration) or, if it's intentionally reserved for future
use (e.g., auth or middleware), add an inline comment above the signature
explaining why request is unused (e.g., "# request kept for future auth guard")
and prefix the variable with an underscore (request -> _request) to signal
intentional non-use. Update any callers or route mappings that expect the old
signature accordingly and ensure imports (Request) are cleaned up if removed.
In `@backend/services/auth_guard.py`:
- Around line 60-61: The except block currently swallows the original exception;
update the handler in auth_guard.py so the broad except Exception captures the
original exception (e.g., except Exception as e:) and re-raise the HTTPException
with exception chaining (raise HTTPException(status_code=401, detail="Not
authenticated") from e) to preserve the original traceback for debugging while
still returning 401 from the authentication function/handler.
In `@backend/tests/test_encryption.py`:
- Around line 99-106: The test test_tampered_ciphertext_raises should assert the
specific AES-GCM tamper exception instead of catching all Exceptions: import
InvalidTag from cryptography.exceptions and change the context manager to with
pytest.raises(InvalidTag): calling encryption.decrypt(tampered). Keep the rest
of the test (encryption.encrypt and bit-flip tampering) unchanged so it still
exercises tamper detection.
In `@frontend/src/app/auth/callback/page.tsx`:
- Around line 70-77: The catch block for the fetch('/api/auth/me') call in
page.tsx silently sets onboardingCompleted = true which can incorrectly skip
onboarding on transient API failures; update the catch to capture the error
(e.g., catch (err)), log it (console.error or your app logger) and set
onboardingCompleted conservatively (false or leave undefined) or implement a
simple retry before deciding, referencing the fetch('/api/auth/me') call and the
onboardingCompleted/local state update to locate the fix.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 0c1bef18-e8e8-4608-9891-9e17ab2b8476

📥 Commits

Reviewing files that changed from the base of the PR and between 1d184ef and ba27384.

📒 Files selected for processing (29)

• backend/.env.example
• backend/db/backfill_encryption.py
• backend/db/migration_encryption_text_columns.sql
• backend/requirements.txt
• backend/routes/admin.py
• backend/routes/auth.py
• backend/routes/calendar.py
• backend/routes/documents.py
• backend/routes/flashcards.py
• backend/routes/gradebook.py
• backend/routes/graph.py
• backend/routes/learn.py
• backend/routes/onboarding.py
• backend/routes/profile.py
• backend/routes/quiz.py
• backend/routes/social.py
• backend/routes/study_guide.py
• backend/services/auth_guard.py
• backend/services/encryption.py
• backend/tests/conftest.py
• backend/tests/test_encryption.py
• backend/tests/test_flashcard_import_routes.py
• backend/tests/test_learn_routes.py
• backend/tests/test_onboarding_routes.py
• backend/tests/test_shared_course_context.py
• backend/tests/test_social_messages.py
• docker-compose.yml
• docs/superpowers/plans/2026-05-03-aes-256-gcm-column-encryption.md
• frontend/src/app/auth/callback/page.tsx

[AndresL230]

Code review

Found 2 issues:

1. resume_session returns encrypted messages.content to the client without decrypting. save_message now writes encrypt_if_present(content) and get_conversation_history correctly applies decrypt_if_present, but resume_session selects id,role,content,created_at from the messages table and returns the rows as-is — users resuming a session will see base64 ciphertext instead of message text.

Sapling/backend/routes/learn.py

Lines 524 to 533 in ba27384

	msgs=table("messages").select(
	"id,role,content,created_at",
	filters={"session_id": f"eq.{session_id}"},
	order="created_at.asc",
	)
	return {
	"session": session_rows[0],
	"messages": msgs,
	}

2. The /auth/me endpoint signature changed to require a verified session (get_session_user_id(request) — accepts only an auth_token query param or sapling_session cookie), but frontend/src/middleware.ts still calls ${API_URL}/api/auth/me?user_id=... from edge middleware without forwarding either credential. Edge fetch() does not auto-forward browser cookies, so every protected-route navigation will receive 401 Not authenticated and fall into the redirectToSignin(request, 'session_expired') branch — full sign-in regression for approved users. The same ?user_id=... pattern is also used by frontend/src/app/api/auth/session/route.ts (fallback path) and frontend/src/context/UserContext.tsx.

Sapling/frontend/src/middleware.ts

Lines 43 to 62 in ba27384

	if(!API_URL)returnredirectToSignin(request,'google_not_configured')
	try{
	constcontroller=newAbortController()
	consttimeout=setTimeout(()=>controller.abort(),3000)
	letres: Response
	try{
	res=awaitfetch(
	`${API_URL}/api/auth/me?user_id=${encodeURIComponent(session.userId)}`,
	{signal: controller.signal},
	)
	}finally{
	clearTimeout(timeout)
	}
	if(!res.ok)returnredirectToSignin(request,'session_expired')
	constdata=awaitres.json()
	if(data.is_approved!==true)returnNextResponse.redirect(newURL('/pending',request.url))
	}catch{
	returnredirectToSignin(request,'signin_failed')
	}

Sapling/backend/services/auth_guard.py

Lines 16 to 51 in ba27384

	def_decode_session(request: Request) ->dict:
	"""Extract and verify the session token from query params or cookies."""
	token=request.query_params.get("auth_token") orrequest.cookies.get("sapling_session")
	ifnottokenornotSESSION_SECRET:
	raiseHTTPException(status_code=401, detail="Not authenticated")
	parts=token.split(".")
	iflen(parts) !=2:
	raiseHTTPException(status_code=401, detail="Invalid session token")
	payload_b64, sig_b64=parts
	# Verify signature
	expected_sig=_hmac.new(
	SESSION_SECRET.encode(), payload_b64.encode(), hashlib.sha256
	).digest()
	expected_b64=base64.urlsafe_b64encode(expected_sig).decode().rstrip("=")
	ifnot_hmac.compare_digest(sig_b64, expected_b64):
	raiseHTTPException(status_code=401, detail="Invalid session token")
	# Decode payload
	padding=4-len(payload_b64) %4
	ifpadding!=4:
	payload_b64+="="*padding
	try:
	payload=json.loads(base64.urlsafe_b64decode(payload_b64).decode())
	exceptException:
	raiseHTTPException(status_code=401, detail="Invalid session token")
	# Check expiry
	ifpayload.get("exp", 0) <int(_time.time()):
	raiseHTTPException(status_code=401, detail="Session expired")
	returnpayload

🤖 Generated with Claude Code

_{- If this code review was useful, please react with 👍. Otherwise, react with 👎.}

[coderabbitai]

Actionable comments posted: 2

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

frontend/src/app/api/auth/session/route.ts (1)

57-70: ⚠️ Potential issue | 🔴 Critical | 🏗️ Heavy lift

Align the sapling_session payload with backend auth_guard.

This route still mints the browser session through signSession(verifiedUserId), but frontend/src/lib/sessionToken.ts:32-41 signs { userId, exp } while backend/services/auth_guard.py:54-64 looks for payload["user_id"]. After this PR, /api/auth/me and the newly request-authenticated backend routes rely on that cookie, so the frontend will accept the session locally but the backend will 401 it and bounce approved users back to sign-in. Please make both sides read/write the same claim name, ideally with backward-compatible decoding during rollout.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.
In `@frontend/src/app/api/auth/session/route.ts` around lines 57 - 70, The
frontend is signing session tokens with a payload using the claim name userId
while the backend auth_guard expects user_id; update the signer used by
signSession (and the payload created in frontend's sessionToken.ts) to emit {
user_id, exp } instead of { userId, exp } or add backward-compatible decoding in
signSession so it also sets user_id when only userId exists, and ensure
verifyAuthToken/signSession continue to produce the cookie name sapling_session
with the same maxAge settings so backend(routes using auth_guard.py) will accept
the cookie during rollout.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@backend/routes/auth.py`:
- Around line 225-230: The calendar token reader must decrypt persisted
ciphertext before building the Credentials object: update the code that
constructs Credentials(...) in backend/routes/calendar.py (where it currently
passes token_row["access_token"] and token_row.get("refresh_token")) to call
decrypt on access_token and decrypt_if_present on refresh_token (or handle
None/empty), and convert the stored expires_at ISO string back to a datetime for
expiry; ensure the same decrypt helper used for encrypt_if_present is referenced
so refresh/decode works after the Google callback writes encrypted tokens.
---
Outside diff comments:
In `@frontend/src/app/api/auth/session/route.ts`:
- Around line 57-70: The frontend is signing session tokens with a payload using
the claim name userId while the backend auth_guard expects user_id; update the
signer used by signSession (and the payload created in frontend's
sessionToken.ts) to emit { user_id, exp } instead of { userId, exp } or add
backward-compatible decoding in signSession so it also sets user_id when only
userId exists, and ensure verifyAuthToken/signSession continue to produce the
cookie name sapling_session with the same maxAge settings so backend(routes
using auth_guard.py) will accept the cookie during rollout.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 01b8fe9a-7972-4263-9df1-4a7b944fcea4

📥 Commits

Reviewing files that changed from the base of the PR and between ba27384 and 43d9015.

📒 Files selected for processing (9)

• backend/routes/auth.py
• backend/routes/documents.py
• backend/routes/flashcards.py
• backend/routes/learn.py
• backend/services/encryption.py
• backend/tests/conftest.py
• backend/tests/test_flashcard_import_routes.py
• frontend/src/app/api/auth/session/route.ts
• frontend/src/middleware.ts

✅ Files skipped from review due to trivial changes (2)

• backend/tests/test_flashcard_import_routes.py
• backend/tests/conftest.py

[coderabbitai]

⚠️ Potential issue | 🟠 Major | 🏗️ Heavy lift

This will orphan pre-existing accounts that don't already have google_id.

When no google_id match exists, the new path always inserts user_{google_id} with is_approved = False. Any existing approved user created before google_id was populated will end up with a second account and lose access to their original courses, documents, graph, and approval state on next sign-in. This needs a transition strategy before merge, such as a one-time backfill of google_id or a temporary legacy-link path that can still find the old row.

[coderabbitai]

⚠️ Potential issue | 🔴 Critical | ⚡ Quick win

Update the calendar token reader in the same rollout.

These writes now persist ciphertext, but backend/routes/calendar.py:35-71 still passes token_row["access_token"] and token_row.get("refresh_token") directly into Credentials(...). After the first successful Google callback, calendar refresh/sync will start using encrypted strings and fail. Please land the matching decrypt-on-read change before shipping this write path.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.
In `@backend/routes/auth.py` around lines 225 - 230, The calendar token reader
must decrypt persisted ciphertext before building the Credentials object: update
the code that constructs Credentials(...) in backend/routes/calendar.py (where
it currently passes token_row["access_token"] and
token_row.get("refresh_token")) to call decrypt on access_token and
decrypt_if_present on refresh_token (or handle None/empty), and convert the
stored expires_at ISO string back to a datetime for expiry; ensure the same
decrypt helper used for encrypt_if_present is referenced so refresh/decode works
after the Google callback writes encrypted tokens.

[AndresL230]

Summary

Adds AES-256-GCM column-level encryption for user PII, OAuth tokens, assignment notes/points, document summaries/concept notes, session summaries, and chat messages. Includes encrypt-on-write + decrypt-on-read across all affected routes, a schema migration that retypes encrypted columns to TEXT, and an idempotent backfill script for existing rows.

Rollout — three things you need to do

1. What to apply to Supabase

Run one SQL file in the Supabase SQL editor: backend/db/migration_encryption_text_columns.sql. It contains four ALTER TABLE ... ALTER COLUMN ... TYPE TEXT USING ::TEXT statements.

Apply it once, before deploying the new code. The casts preserve existing rows as TEXT (e.g., 87.5 becomes the string "87.5"); the decrypt_if_present / decrypt_numeric fallbacks keep those legacy rows readable until you backfill.

2. Values you need to set

Just one new env var. ENCRYPTION_KEY = 64 hex chars (32 bytes). Generate it with:

python -c "import secrets; print(secrets.token_hex(32))"

Set it in:

• backend/.env for local dev (backend/.env.example already has the placeholder + the generation command).
• Wherever your backend actually runs in deploy (Cloudflare Workers/Pages env vars, Vercel, Fly, Railway, whatever — the same place SUPABASE_SERVICE_KEY is set today). docker-compose.yml already passes it through from backend/.env.

Two non-negotiables:

• The same key must be used everywhere your backend runs. Different keys = ciphertext written by one instance is unreadable by another.
• Never rotate or lose this key. Losing it permanently bricks every encrypted column. If you need to rotate, write a script that decrypts with the old key and re-encrypts with the new one in one transaction.

The backend will refuse to boot if ENCRYPTION_KEY is missing, not 64 chars, or not valid hex (intentional fail-fast).

3. The backfill script

backend/db/backfill_encryption.py. For each encrypted column on each table (users.name/email/bio/..., oauth_tokens.access_token/refresh_token, assignments.notes/points_*, documents.summary/concept_notes, sessions.summary_json, messages.content, room_messages.text), it:

1. Selects every row.
2. For each cell, calls decrypt(value) once.
3. If it succeeds → already encrypted → skip.
4. If it raises → the cell is still legacy plaintext → encrypt it and write back.

Prints counts per column. Idempotent — running it a second time changes nothing. Defaults to dry-run (counts only); --apply to actually write. --table users to do it in stages.

How to actually run all of this, in order

# 1. Generate and set the key
python -c "import secrets; print(secrets.token_hex(32))"# paste output as ENCRYPTION_KEY=... in backend/.env# AND set the same value in your deploy environment# 2. Apply the schema migration in Supabase# Dashboard → SQL Editor → paste contents of:# backend/db/migration_encryption_text_columns.sql → Run# 3. Deploy the new backend code (encryption wiring is on this branch)# 4. Backfill — first dry-run to see what will change:cd backend
.\venv\Scripts\python.exe -m db.backfill_encryption
# 5. Then actually apply:
.\venv\Scripts\python.exe -m db.backfill_encryption --apply

After the backfill completes successfully, the decrypt_if_present fallback-to-raw-value warnings should stop appearing in logs. That's the signal it worked.

Test plan

• Apply migration_encryption_text_columns.sql to a Supabase branch DB
• Set ENCRYPTION_KEY (64-hex) and confirm backend boots; confirm it refuses to boot when the var is missing/invalid
• Run backend tests: cd backend && python -m pytest tests/ -q (includes new test_encryption.py)
• Sign in via Google OAuth → confirm users.name/email written as ciphertext, /me returns plaintext
• Upload a document → confirm documents.summary/concept_notes ciphertext at rest, decrypt on library/study-guide/flashcards reads
• Sync calendar → confirm oauth_tokens.access_token/refresh_token and assignments.notes/points_* encrypted
• Send a room message + a learn-session message → confirm room_messages.text and messages.content encrypted
• Run backfill in dry-run on a copy of prod data, verify counts, then --apply and re-run to confirm idempotency (zero changes)
• Confirm decrypt_if_present fallback warnings disappear from logs after backfill

Summary by CodeRabbit

• New Features

  • End-to-end encryption for sensitive data (profiles, documents, sessions, messages, tokens).

• Improvements

  • Decryption in responses and encryption on save for many user-facing flows.
  • Tighter per-request authorization across endpoints and stricter ownership checks.

• Chores

  • Added encryption key configuration and dependency updates; adjusted schema to support encrypted values.

• Tests & Docs

  • Added encryption test coverage and an implementation/rollout plan.

[cloudflare-workers-and-pages]

Deploying with Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Preview URL	Updated (UTC)
✅ Deployment successful! View logs	frontend	43d9015	Commit Preview URL Branch Preview URL	May 03 2026, 07:57 PM

[coderabbitai]

📝 Walkthrough

Walkthrough

Adds AES-256-GCM column-level encryption: new encryption service, test coverage, env/docker wiring, a migration to TEXT for certain columns, a one-shot backfill CLI, and pervasive route changes to encrypt sensitive writes, decrypt reads, and enforce request-based authorization.

Changes

Encryption rollout & route wiring

Layer / File(s)	Summary
Data Shape / Schema Prep backend/db/migration_encryption_text_columns.sql	Retypes specific numeric/JSONB columns to TEXT using USING <col>::TEXT to allow storing ciphertext strings.
Dependencies backend/requirements.txt	Pins cryptography (>=42,<46).
Environment backend/.env.example, docker-compose.yml	Adds ENCRYPTION_KEY placeholder and passes ${ENCRYPTION_KEY} into the backend service.
Encryption Core backend/services/encryption.py	New AES-256-GCM helpers: key loader/validation, encrypt/decrypt, encrypt_if_present/decrypt_if_present, decrypt_numeric, encrypt_json/decrypt_json.
Backfill Tool backend/db/backfill_encryption.py	One-shot CLI that scans configured tables/columns, detects already-encrypted vs legacy plaintext/JSON/numeric values, and optionally writes encrypted values with --apply.
Auth Guard Tightening backend/services/auth_guard.py	get_session_user_id now requires a valid session token (no query-param fallback) and raises 401 on missing/invalid payload.
Route Integration (reads/writes & auth) backend/routes/*.py (auth, onboarding, profile, admin, social, quiz, learn, calendar, gradebook, documents, flashcards, study_guide, graph)	Handlers now accept Request where applicable, enforce require_self/session ownership, encrypt sensitive fields on write and decrypt on read, and narrow SELECT projections. OAuth tokens are decrypted for use and encrypted on refresh/storage. Several patch/allowlist behaviors adjusted to exclude sensitive fields.
Frontend adjustments frontend/src/app/auth/callback/page.tsx, frontend/src/app/api/auth/session/route.ts, frontend/src/middleware.ts	Auth callback no longer requires name param and fetches /api/auth/me from session; session route now requires/verifies authToken; middleware forwards sapling_session cookie to backend auth check.
Tests & Test Setup backend/tests/conftest.py, backend/tests/test_encryption.py, backend/tests/*	Deterministic test key in env, autouse fixture bypasses session auth for route tests, new encryption unit tests (string/JSON/numeric/nonce/tamper), and multiple route test updates to accommodate request-based auth and encrypted fields.
Docs / Plan docs/superpowers/plans/2026-05-03-aes-256-gcm-column-encryption.md	Comprehensive rollout plan, inventory of # ENCRYPTED LATER markers, migration/backfill instructions, and follow-up tasks.

Sequence Diagram

sequenceDiagram
participant Client
participant RouteHandler
participant AuthGuard
participant EncryptionSvc
participant Database
rect rgba(100, 150, 200, 0.5)
Note over Client,Database: Write path (encrypt before persist)
Client->>RouteHandler: POST /api/... (user_id, sensitive)
RouteHandler->>AuthGuard: require_self(user_id, request)
AuthGuard-->>RouteHandler: authorized
RouteHandler->>EncryptionSvc: encrypt(sensitive)
EncryptionSvc-->>RouteHandler: ciphertext
RouteHandler->>Database: INSERT/UPDATE (ciphertext)
Database-->>RouteHandler: OK
RouteHandler-->>Client: 200 (response with decrypted fields)
end
rect rgba(150, 200, 100, 0.5)
Note over Client,Database: Read path (decrypt on load)
Client->>RouteHandler: GET /api/.../{user_id}
RouteHandler->>AuthGuard: require_self(user_id, request)
AuthGuard-->>RouteHandler: authorized
RouteHandler->>Database: SELECT (ciphertext_field)
Database-->>RouteHandler: row with ciphertext
RouteHandler->>EncryptionSvc: decrypt_if_present(ciphertext)
EncryptionSvc-->>RouteHandler: plaintext or legacy value
RouteHandler-->>Client: 200 (plaintext)
end
rect rgba(200, 100, 100, 0.5)
Note over RouteHandler,EncryptionSvc: Legacy plaintext fallback
RouteHandler->>EncryptionSvc: decrypt_if_present(legacy_plaintext)
EncryptionSvc-->>RouteHandler: returns original plaintext (logs warning)
end

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Possibly related PRs

• adding approval gate for closed beta #56: Overlaps changes to backend/routes/auth.py GET /me (authorization and returned fields).
• Course ID schema migration + calendar assignment normalization #53: Overlaps calendar assignment flows and OAuth token handling in backend/routes/calendar.py.
• Frontend revamp (M1-M9 + deferred items + production hardening) #62: Related frontend session handling changes to frontend/src/app/api/auth/session/route.ts (cookie/session verification).

Poem

🐰
I hopped through code at dawn's first light,
Wrapped secrets snug in AES so tight,
Nonces fresh, each byte takes flight,
Now data sleeps secure each night.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 16.56% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'feat: AES-256-GCM column-level encryption for user PII' directly and clearly summarizes the main feature being added—column-level encryption for sensitive user data.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description check	✅ Passed	The PR description comprehensively covers what the PR does, why, rollout steps, environment configuration, backfill instructions, and test plan—all aligned with the description template structure.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/aes-256-gcm-encryption

Tip

💬 Introducing Slack Agent: The best way for teams to turn conversations into code.

Slack Agent is built on CodeRabbit's deep understanding of your code, so your team can collaborate across the entire SDLC without losing context.

• Generate code and open pull requests
• Plan features and break down work
• Investigate incidents and troubleshoot customer tickets together
• Automate recurring tasks and respond to alerts with triggers
• Summarize progress and report instantly

Built for teams:

• Shared memory across your entire org—no repeating context
• Per-thread sandboxes to safely plan and execute work
• Governance built-in—scoped access, auditability, and budget controls

One agent for your entire SDLC. Right inside Slack.

👉 Get started

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 4

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (4)

backend/routes/quiz.py (1)

190-203: ⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Guard student_name against nulls before template replacement.

decrypt_if_present() can return None. If users.name is null, the .replace("{student_name}", student_name) call raises TypeError after the quiz attempt and mastery updates have already been persisted.

Suggested fix

- student_name = decrypt_if_present(user_rows[0]["name"]) if user_rows else "Student"+ student_name = (+ decrypt_if_present(user_rows[0].get("name")) or "Student"+ if user_rows+ else "Student"+ )

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.
In `@backend/routes/quiz.py` around lines 190 - 203, The student_name value used
in the prompt can be None because decrypt_if_present(user_rows[0]["name"]) may
return None; before calling .replace("{student_name}", student_name) ensure
student_name is a non-null string (e.g., coerce to a fallback like "Student" or
"" if None) so template replacement never receives None; update the code around
where student_name is assigned (the decrypt_if_present call and subsequent use
in ctx_prompt/_load_prompt) to coerce or default the value and use that
sanitized variable in the .replace call.

backend/routes/gradebook.py (1)

242-255: ⚠️ Potential issue | 🟠 Major | ⚡ Quick win

Return decrypted fields from create_assignment().

This route now writes encrypted points_possible, points_earned, and notes, then returns inserted[0] verbatim. Any client that uses the POST response to update local state will receive ciphertext instead of the values it just submitted, while the read endpoints return plaintext.

Suggested fix

 inserted = table("assignments").insert({
"id": new_id,
"user_id": body.user_id,
"course_id": body.course_id,
"title": body.title,
"category_id": body.category_id,
"points_possible": encrypt_if_present(body.points_possible),
"points_earned": encrypt_if_present(body.points_earned),
"due_date": body.due_date,
"assignment_type": body.assignment_type,
"notes": encrypt_if_present(body.notes),
"source": "manual",
})
- return {"assignment": inserted[0] if inserted else None}+ assignment = inserted[0] if inserted else None+ if assignment:+ assignment["points_possible"] = decrypt_numeric(assignment.get("points_possible"))+ assignment["points_earned"] = decrypt_numeric(assignment.get("points_earned"))+ assignment["notes"] = decrypt_if_present(assignment.get("notes"))+ return {"assignment": assignment}

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.
In `@backend/routes/gradebook.py` around lines 242 - 255, The POST handler
currently inserts encrypted values (using encrypt_if_present) and returns
inserted[0] as-is, causing ciphertext to be returned; after the insert in
create_assignment (the block that builds inserted =
table("assignments").insert(...)), decrypt the stored fields before returning by
running points_possible, points_earned, and notes through the corresponding
decrypt helper (e.g., decrypt_if_present) and then return the modified
assignment object (rather than the raw inserted[0]); update the return to return
{"assignment": decrypted_assignment} so clients receive plaintext fields
consistent with read endpoints.

backend/routes/learn.py (1)

525-532: ⚠️ Potential issue | 🟠 Major | ⚡ Quick win

Messages returned by resume_session are not decrypted.

When resuming a persisted session, the messages fetched from the database have encrypted content but are returned directly without decryption. This is inconsistent with get_conversation_history which decrypts message content.

🐛 Proposed fix

 msgs = table("messages").select(
"id,role,content,created_at",
filters={"session_id": f"eq.{session_id}"},
order="created_at.asc",
)
+ for m in msgs:+ m["content"] = decrypt_if_present(m.get("content"))
return {
"session": session_rows[0],
"messages": msgs,
}

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.
In `@backend/routes/learn.py` around lines 525 - 532, The messages returned by
resume_session are fetched into msgs via table("messages").select but not
decrypted; update resume_session to reuse the decryption logic from
get_conversation_history (or call get_conversation_history(session_id) instead
of returning raw msgs) so each message's content is decrypted before returning.
Locate the msgs variable and the return that currently returns session_rows[0]
and msgs, then either map over msgs and replace each message's content with the
decrypted value using the same helper used by get_conversation_history, or
delegate to get_conversation_history to produce the decrypted messages, and
return that result.

backend/routes/social.py (1)

343-371: ⚠️ Potential issue | 🟠 Major

user_name is stored unencrypted in room_messages.

The message text is encrypted but body.user_name is stored in plaintext. This is inconsistent with the PR's goal of encrypting PII. User names are PII and should be encrypted at rest.

This also requires updating get_room_messages to decrypt user_name in the message rows (line 290) and reply snippets (line 320).

🔒 Proposed fix to encrypt user_name

 row = table("room_messages").insert({
"room_id": room_id,
"user_id": body.user_id,
- "user_name": body.user_name,+ "user_name": encrypt_if_present(body.user_name),
"text": encrypt_if_present(body.text or None),
"image_url": body.image_url or None,
"reply_to_id": body.reply_to_id or None,
})
if row:
row[0]["text"] = decrypt_if_present(row[0].get("text"))
+ row[0]["user_name"] = decrypt_if_present(row[0].get("user_name"))

In get_room_messages, decrypt user_name when retrieving message rows and reply snippets.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.
In `@backend/routes/social.py` around lines 343 - 371, send_room_message currently
stores body.user_name in plaintext; update the insert in send_room_message to
pass user_name through encrypt_if_present (same pattern as text) so user_name is
encrypted at rest. Then update get_room_messages to call decrypt_if_present on
the message row's user_name and also on any reply snippet user_name (the
reply_to handling at/around where reply snippets are built) to return decrypted
names to clients; preserve null/None handling consistent with
encrypt_if_present/decrypt_if_present usage.

🧹 Nitpick comments (8)

backend/services/auth_guard.py (1)

60-61: 💤 Low value

Add exception chaining for better error tracing.

While catching a broad Exception is acceptable here (any decode failure should yield 401), using raise ... from would preserve the original exception context for debugging.

♻️ Suggested improvement

- except Exception:- raise HTTPException(status_code=401, detail="Not authenticated")+ except Exception as exc:+ raise HTTPException(status_code=401, detail="Not authenticated") from exc

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.
In `@backend/services/auth_guard.py` around lines 60 - 61, The except block
currently swallows the original exception; update the handler in auth_guard.py
so the broad except Exception captures the original exception (e.g., except
Exception as e:) and re-raise the HTTPException with exception chaining (raise
HTTPException(status_code=401, detail="Not authenticated") from e) to preserve
the original traceback for debugging while still returning 401 from the
authentication function/handler.

backend/routes/onboarding.py (1)

14-14: 💤 Low value

Unused request parameter in search_courses.

The request: Request parameter is accepted but never used in this function. If this is intentional for consistency or future auth guards, consider adding a comment. Otherwise, remove it to avoid confusion.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.
In `@backend/routes/onboarding.py` at line 14, The function search_courses
currently declares an unused parameter request: Request which causes confusion;
either remove the request parameter from the function signature of
search_courses (and any corresponding route decorator/handler registration) or,
if it's intentionally reserved for future use (e.g., auth or middleware), add an
inline comment above the signature explaining why request is unused (e.g., "#
request kept for future auth guard") and prefix the variable with an underscore
(request -> _request) to signal intentional non-use. Update any callers or route
mappings that expect the old signature accordingly and ensure imports (Request)
are cleaned up if removed.

backend/db/backfill_encryption.py (2)

91-91: 🏗️ Heavy lift

No pagination — large tables may cause memory/timeout issues.

table(table_name).select(...) on line 91 (and similar calls) loads all rows into memory. For tables with millions of rows (e.g., messages, room_messages), this could exhaust memory or timeout.

Consider adding batching with limit and offset, or using cursor-based pagination:

Example batch approach

BATCH_SIZE=1000offset=0whileTrue:
rows=table(table_name).select(
",".join([pk, *columns]),
limit=BATCH_SIZE,
offset=offset,
order=f"{pk}.asc"
) or []
ifnotrows:
break# process rows...offset+=BATCH_SIZE

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.
In `@backend/db/backfill_encryption.py` at line 91, The current call rows =
table(table_name).select(",".join([pk, *columns])) loads the entire table into
memory; change the logic around table(table_name).select to iterate in batches
(use limit/offset or a cursor) while selecting the same columns (referencing
table_name, pk, columns and the table(...) call) so you fetch e.g. BATCH_SIZE
rows at a time, process them, then advance the offset (or cursor) and repeat
until no rows remain; ensure you preserve ordering (order by pk) to make
pagination deterministic and avoid loading all rows into memory.

---

162-172: 💤 Low value

Corrupt JSON encrypted as raw string may cause decrypt mismatch.

When JSON parsing fails (line 164), the raw string is encrypted via encrypt(v) (line 169). However, reads use decrypt_json() which expects json.loads(decrypt(value)). Decrypting will succeed, but json.loads will fail on the corrupt JSON, triggering the fallback path.

This is acceptable since the fallback handles it, but documenting this behavior would help future maintainers understand why some cells fail JSON parsing after decryption.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.
In `@backend/db/backfill_encryption.py` around lines 162 - 172, When JSON parsing
fails in backfill_encryption.py (the _json.loads(v) exception path), we
currently encrypt the raw string with encrypt(v) so the value can round-trip
through decrypt_if_present/decrypt_json(); add a clear inline comment near the
except block explaining that decrypt_json() will call json.loads(decrypt(value))
and therefore decrypted corrupt JSON will re-trigger the JSON parse fallback at
read time, and that this is intentional because the runtime fallback will handle
it; reference the functions _json.loads, encrypt, decrypt_json, and
decrypt_if_present in the comment so future maintainers understand the
round-trip behavior and why some cells may still fail JSON parsing after
decryption.

frontend/src/app/auth/callback/page.tsx (1)

70-77: 💤 Low value

Silent failure fallback masks /api/auth/me errors.

When the /api/auth/me fetch fails (line 75), the code defaults onboardingCompleted = true, which could incorrectly skip onboarding for users who haven't completed it if the API is temporarily unavailable. Consider logging this case or retrying.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.
In `@frontend/src/app/auth/callback/page.tsx` around lines 70 - 77, The catch
block for the fetch('/api/auth/me') call in page.tsx silently sets
onboardingCompleted = true which can incorrectly skip onboarding on transient
API failures; update the catch to capture the error (e.g., catch (err)), log it
(console.error or your app logger) and set onboardingCompleted conservatively
(false or leave undefined) or implement a simple retry before deciding,
referencing the fetch('/api/auth/me') call and the onboardingCompleted/local
state update to locate the fix.

backend/routes/flashcards.py (1)

128-137: 💤 Low value

Silent pass on decrypt failure is acceptable but consider logging.

The try-except-pass on lines 133-136 silently ignores decryption failures for concept_notes. While this is intentional for legacy plaintext compatibility, the encryption module's docstring mentions "fallback logs a warning." Consider adding a logging statement here for consistency with the stated rollout observability.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.
In `@backend/routes/flashcards.py` around lines 128 - 137, The code silently
swallows exceptions when calling decrypt_json on d.get("concept_notes"); instead
add a warning log inside the except to surface the failure (include context like
the doc id/index and use exc_info=True or log the exception message) while
preserving the fallback behavior of leaving concept_notes unchanged; reference
the decrypt_json call and d["concept_notes"], and ensure you use the module
logger (e.g., obtain logging.getLogger(__name__) or reuse an existing logger
variable) before logging.

backend/routes/learn.py (1)

231-239: ⚡ Quick win

Use explicit None union type annotation.

PEP 484 prohibits implicit Optional. The type hint should use | None for clarity.

♻️ Proposed fix

-def save_message(session_id: str, role: str, content: str, graph_update: dict = None):+def save_message(session_id: str, role: str, content: str, graph_update: dict | None = None):

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.
In `@backend/routes/learn.py` around lines 231 - 239, Update the function
signature for save_message to use an explicit None union type for the
graph_update parameter: replace the implicit Optional style "graph_update: dict
= None" with the explicit union form "graph_update: dict | None = None"
(referencing the save_message function and the graph_update parameter) so the
type hint conforms to PEP 484; ensure no other code changes are required.

backend/tests/test_encryption.py (1)

99-106: Use specific exception type for tamper detection test.

The test currently catches Exception, which is too broad. AES-GCM tamper detection raises cryptography.exceptions.InvalidTag, and using the specific exception type makes the test more precise and prevents accidentally passing if a different exception is raised.

♻️ Proposed fix

 def test_tampered_ciphertext_raises():
import base64
+ from cryptography.exceptions import InvalidTag
ct = encryption.encrypt("secret")
raw = bytearray(base64.b64decode(ct))
raw[-1] ^= 0x01 # flip one bit in the tag
tampered = base64.b64encode(bytes(raw)).decode()
- with pytest.raises(Exception):+ with pytest.raises(InvalidTag):
encryption.decrypt(tampered)

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.
In `@backend/tests/test_encryption.py` around lines 99 - 106, The test
test_tampered_ciphertext_raises should assert the specific AES-GCM tamper
exception instead of catching all Exceptions: import InvalidTag from
cryptography.exceptions and change the context manager to with
pytest.raises(InvalidTag): calling encryption.decrypt(tampered). Keep the rest
of the test (encryption.encrypt and bit-flip tampering) unchanged so it still
exercises tamper detection.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@backend/db/migration_encryption_text_columns.sql`:
- Around line 13-27: The migration casts documents.concept_notes and
sessions.summary_json to TEXT but services/encryption.py's decrypt_json() lacks
the legacy-plaintext fallback, so pre-backfill rows will break; update
decrypt_json() (in backend/services/encryption.py) to detect and return
plaintext JSON when input isn't valid ciphertext (similar to the scalar
fallbacks used by decrypt_text()/decrypt_number()), or alternatively ensure the
DB backfill and enabling of readers are performed atomically so decrypt_json()
never sees legacy plaintext—modify either decrypt_json() to include a JSON
fallback helper or adjust the deployment/migration process to run the backfill
before enabling readers for documents.concept_notes and sessions.summary_json.
In `@backend/routes/auth.py`:
- Around line 228-229: The code is encrypting an empty string when
creds.refresh_token is None (calling encrypt("")), causing inconsistent handling
vs backfilled rows; change the assignment that sets "refresh_token" to either
call encrypt_if_present(creds.refresh_token) or keep a None value when
creds.refresh_token is falsy so empty strings are not encrypted—update the
object construction where "refresh_token" is set (referencing encrypt and
creds.refresh_token) to use encrypt_if_present or conditional preservation of
None to match the backfill behavior.
In `@backend/services/encryption.py`:
- Around line 116-117: decrypt_json currently assumes input is encrypted and
will raise if passed legacy plaintext JSON; update decrypt_json to mirror
decrypt_if_present by attempting to decrypt then json.loads, but on decryption
failure (or if decrypted result is invalid) fall back to json.loads(value) so
pre-encryption JSON still parses; locate the decrypt_json function and wrap its
call to decrypt(value) in a try/except (or check the decrypt result) and use
json.loads(value) as the fallback.
In `@backend/tests/conftest.py`:
- Around line 32-69: The current fixture only monkeypatches already-imported
route modules, leaving services.auth_guard itself untouched and causing
import-order dependent behavior; update the fixture to also monkeypatch the
functions on the services.auth_guard module (replace auth_guard._decode_session
with _decode_session_stub and auth_guard.get_session_user_id,
auth_guard.require_self, auth_guard.require_admin, and auth_guard.require_role
with the corresponding stubs/_require_role_stub) so any later-imported routes
that reference auth_guard will get the bypassed implementations; keep the
existing stubs (_decode_session_stub, _get_session_user_id_stub,
_require_self_stub, _require_admin_stub, _require_role_stub) and use
monkeypatch.setattr(auth_guard, "<name>", <stub>) for each symbol.
---
Outside diff comments:
In `@backend/routes/gradebook.py`:
- Around line 242-255: The POST handler currently inserts encrypted values
(using encrypt_if_present) and returns inserted[0] as-is, causing ciphertext to
be returned; after the insert in create_assignment (the block that builds
inserted = table("assignments").insert(...)), decrypt the stored fields before
returning by running points_possible, points_earned, and notes through the
corresponding decrypt helper (e.g., decrypt_if_present) and then return the
modified assignment object (rather than the raw inserted[0]); update the return
to return {"assignment": decrypted_assignment} so clients receive plaintext
fields consistent with read endpoints.
In `@backend/routes/learn.py`:
- Around line 525-532: The messages returned by resume_session are fetched into
msgs via table("messages").select but not decrypted; update resume_session to
reuse the decryption logic from get_conversation_history (or call
get_conversation_history(session_id) instead of returning raw msgs) so each
message's content is decrypted before returning. Locate the msgs variable and
the return that currently returns session_rows[0] and msgs, then either map over
msgs and replace each message's content with the decrypted value using the same
helper used by get_conversation_history, or delegate to get_conversation_history
to produce the decrypted messages, and return that result.
In `@backend/routes/quiz.py`:
- Around line 190-203: The student_name value used in the prompt can be None
because decrypt_if_present(user_rows[0]["name"]) may return None; before calling
.replace("{student_name}", student_name) ensure student_name is a non-null
string (e.g., coerce to a fallback like "Student" or "" if None) so template
replacement never receives None; update the code around where student_name is
assigned (the decrypt_if_present call and subsequent use in
ctx_prompt/_load_prompt) to coerce or default the value and use that sanitized
variable in the .replace call.
In `@backend/routes/social.py`:
- Around line 343-371: send_room_message currently stores body.user_name in
plaintext; update the insert in send_room_message to pass user_name through
encrypt_if_present (same pattern as text) so user_name is encrypted at rest.
Then update get_room_messages to call decrypt_if_present on the message row's
user_name and also on any reply snippet user_name (the reply_to handling
at/around where reply snippets are built) to return decrypted names to clients;
preserve null/None handling consistent with
encrypt_if_present/decrypt_if_present usage.
---
Nitpick comments:
In `@backend/db/backfill_encryption.py`:
- Line 91: The current call rows = table(table_name).select(",".join([pk,
*columns])) loads the entire table into memory; change the logic around
table(table_name).select to iterate in batches (use limit/offset or a cursor)
while selecting the same columns (referencing table_name, pk, columns and the
table(...) call) so you fetch e.g. BATCH_SIZE rows at a time, process them, then
advance the offset (or cursor) and repeat until no rows remain; ensure you
preserve ordering (order by pk) to make pagination deterministic and avoid
loading all rows into memory.
- Around line 162-172: When JSON parsing fails in backfill_encryption.py (the
_json.loads(v) exception path), we currently encrypt the raw string with
encrypt(v) so the value can round-trip through
decrypt_if_present/decrypt_json(); add a clear inline comment near the except
block explaining that decrypt_json() will call json.loads(decrypt(value)) and
therefore decrypted corrupt JSON will re-trigger the JSON parse fallback at read
time, and that this is intentional because the runtime fallback will handle it;
reference the functions _json.loads, encrypt, decrypt_json, and
decrypt_if_present in the comment so future maintainers understand the
round-trip behavior and why some cells may still fail JSON parsing after
decryption.
In `@backend/routes/flashcards.py`:
- Around line 128-137: The code silently swallows exceptions when calling
decrypt_json on d.get("concept_notes"); instead add a warning log inside the
except to surface the failure (include context like the doc id/index and use
exc_info=True or log the exception message) while preserving the fallback
behavior of leaving concept_notes unchanged; reference the decrypt_json call and
d["concept_notes"], and ensure you use the module logger (e.g., obtain
logging.getLogger(__name__) or reuse an existing logger variable) before
logging.
In `@backend/routes/learn.py`:
- Around line 231-239: Update the function signature for save_message to use an
explicit None union type for the graph_update parameter: replace the implicit
Optional style "graph_update: dict = None" with the explicit union form
"graph_update: dict | None = None" (referencing the save_message function and
the graph_update parameter) so the type hint conforms to PEP 484; ensure no
other code changes are required.
In `@backend/routes/onboarding.py`:
- Line 14: The function search_courses currently declares an unused parameter
request: Request which causes confusion; either remove the request parameter
from the function signature of search_courses (and any corresponding route
decorator/handler registration) or, if it's intentionally reserved for future
use (e.g., auth or middleware), add an inline comment above the signature
explaining why request is unused (e.g., "# request kept for future auth guard")
and prefix the variable with an underscore (request -> _request) to signal
intentional non-use. Update any callers or route mappings that expect the old
signature accordingly and ensure imports (Request) are cleaned up if removed.
In `@backend/services/auth_guard.py`:
- Around line 60-61: The except block currently swallows the original exception;
update the handler in auth_guard.py so the broad except Exception captures the
original exception (e.g., except Exception as e:) and re-raise the HTTPException
with exception chaining (raise HTTPException(status_code=401, detail="Not
authenticated") from e) to preserve the original traceback for debugging while
still returning 401 from the authentication function/handler.
In `@backend/tests/test_encryption.py`:
- Around line 99-106: The test test_tampered_ciphertext_raises should assert the
specific AES-GCM tamper exception instead of catching all Exceptions: import
InvalidTag from cryptography.exceptions and change the context manager to with
pytest.raises(InvalidTag): calling encryption.decrypt(tampered). Keep the rest
of the test (encryption.encrypt and bit-flip tampering) unchanged so it still
exercises tamper detection.
In `@frontend/src/app/auth/callback/page.tsx`:
- Around line 70-77: The catch block for the fetch('/api/auth/me') call in
page.tsx silently sets onboardingCompleted = true which can incorrectly skip
onboarding on transient API failures; update the catch to capture the error
(e.g., catch (err)), log it (console.error or your app logger) and set
onboardingCompleted conservatively (false or leave undefined) or implement a
simple retry before deciding, referencing the fetch('/api/auth/me') call and the
onboardingCompleted/local state update to locate the fix.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 0c1bef18-e8e8-4608-9891-9e17ab2b8476

📥 Commits

Reviewing files that changed from the base of the PR and between 1d184ef and ba27384.

📒 Files selected for processing (29)

• backend/.env.example
• backend/db/backfill_encryption.py
• backend/db/migration_encryption_text_columns.sql
• backend/requirements.txt
• backend/routes/admin.py
• backend/routes/auth.py
• backend/routes/calendar.py
• backend/routes/documents.py
• backend/routes/flashcards.py
• backend/routes/gradebook.py
• backend/routes/graph.py
• backend/routes/learn.py
• backend/routes/onboarding.py
• backend/routes/profile.py
• backend/routes/quiz.py
• backend/routes/social.py
• backend/routes/study_guide.py
• backend/services/auth_guard.py
• backend/services/encryption.py
• backend/tests/conftest.py
• backend/tests/test_encryption.py
• backend/tests/test_flashcard_import_routes.py
• backend/tests/test_learn_routes.py
• backend/tests/test_onboarding_routes.py
• backend/tests/test_shared_course_context.py
• backend/tests/test_social_messages.py
• docker-compose.yml
• docs/superpowers/plans/2026-05-03-aes-256-gcm-column-encryption.md
• frontend/src/app/auth/callback/page.tsx

[AndresL230]

Code review

Found 2 issues:

1. resume_session returns encrypted messages.content to the client without decrypting. save_message now writes encrypt_if_present(content) and get_conversation_history correctly applies decrypt_if_present, but resume_session selects id,role,content,created_at from the messages table and returns the rows as-is — users resuming a session will see base64 ciphertext instead of message text.

Sapling/backend/routes/learn.py

Lines 524 to 533 in ba27384

	msgs=table("messages").select(
	"id,role,content,created_at",
	filters={"session_id": f"eq.{session_id}"},
	order="created_at.asc",
	)
	return {
	"session": session_rows[0],
	"messages": msgs,
	}

2. The /auth/me endpoint signature changed to require a verified session (get_session_user_id(request) — accepts only an auth_token query param or sapling_session cookie), but frontend/src/middleware.ts still calls ${API_URL}/api/auth/me?user_id=... from edge middleware without forwarding either credential. Edge fetch() does not auto-forward browser cookies, so every protected-route navigation will receive 401 Not authenticated and fall into the redirectToSignin(request, 'session_expired') branch — full sign-in regression for approved users. The same ?user_id=... pattern is also used by frontend/src/app/api/auth/session/route.ts (fallback path) and frontend/src/context/UserContext.tsx.

Sapling/frontend/src/middleware.ts

Lines 43 to 62 in ba27384

	if(!API_URL)returnredirectToSignin(request,'google_not_configured')
	try{
	constcontroller=newAbortController()
	consttimeout=setTimeout(()=>controller.abort(),3000)
	letres: Response
	try{
	res=awaitfetch(
	`${API_URL}/api/auth/me?user_id=${encodeURIComponent(session.userId)}`,
	{signal: controller.signal},
	)
	}finally{
	clearTimeout(timeout)
	}
	if(!res.ok)returnredirectToSignin(request,'session_expired')
	constdata=awaitres.json()
	if(data.is_approved!==true)returnNextResponse.redirect(newURL('/pending',request.url))
	}catch{
	returnredirectToSignin(request,'signin_failed')
	}

Sapling/backend/services/auth_guard.py

Lines 16 to 51 in ba27384

	def_decode_session(request: Request) ->dict:
	"""Extract and verify the session token from query params or cookies."""
	token=request.query_params.get("auth_token") orrequest.cookies.get("sapling_session")
	ifnottokenornotSESSION_SECRET:
	raiseHTTPException(status_code=401, detail="Not authenticated")
	parts=token.split(".")
	iflen(parts) !=2:
	raiseHTTPException(status_code=401, detail="Invalid session token")
	payload_b64, sig_b64=parts
	# Verify signature
	expected_sig=_hmac.new(
	SESSION_SECRET.encode(), payload_b64.encode(), hashlib.sha256
	).digest()
	expected_b64=base64.urlsafe_b64encode(expected_sig).decode().rstrip("=")
	ifnot_hmac.compare_digest(sig_b64, expected_b64):
	raiseHTTPException(status_code=401, detail="Invalid session token")
	# Decode payload
	padding=4-len(payload_b64) %4
	ifpadding!=4:
	payload_b64+="="*padding
	try:
	payload=json.loads(base64.urlsafe_b64decode(payload_b64).decode())
	exceptException:
	raiseHTTPException(status_code=401, detail="Invalid session token")
	# Check expiry
	ifpayload.get("exp", 0) <int(_time.time()):
	raiseHTTPException(status_code=401, detail="Session expired")
	returnpayload

🤖 Generated with Claude Code

_{- If this code review was useful, please react with 👍. Otherwise, react with 👎.}

[coderabbitai]

Actionable comments posted: 2

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

frontend/src/app/api/auth/session/route.ts (1)

57-70: ⚠️ Potential issue | 🔴 Critical | 🏗️ Heavy lift

Align the sapling_session payload with backend auth_guard.

This route still mints the browser session through signSession(verifiedUserId), but frontend/src/lib/sessionToken.ts:32-41 signs { userId, exp } while backend/services/auth_guard.py:54-64 looks for payload["user_id"]. After this PR, /api/auth/me and the newly request-authenticated backend routes rely on that cookie, so the frontend will accept the session locally but the backend will 401 it and bounce approved users back to sign-in. Please make both sides read/write the same claim name, ideally with backward-compatible decoding during rollout.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.
In `@frontend/src/app/api/auth/session/route.ts` around lines 57 - 70, The
frontend is signing session tokens with a payload using the claim name userId
while the backend auth_guard expects user_id; update the signer used by
signSession (and the payload created in frontend's sessionToken.ts) to emit {
user_id, exp } instead of { userId, exp } or add backward-compatible decoding in
signSession so it also sets user_id when only userId exists, and ensure
verifyAuthToken/signSession continue to produce the cookie name sapling_session
with the same maxAge settings so backend(routes using auth_guard.py) will accept
the cookie during rollout.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@backend/routes/auth.py`:
- Around line 225-230: The calendar token reader must decrypt persisted
ciphertext before building the Credentials object: update the code that
constructs Credentials(...) in backend/routes/calendar.py (where it currently
passes token_row["access_token"] and token_row.get("refresh_token")) to call
decrypt on access_token and decrypt_if_present on refresh_token (or handle
None/empty), and convert the stored expires_at ISO string back to a datetime for
expiry; ensure the same decrypt helper used for encrypt_if_present is referenced
so refresh/decode works after the Google callback writes encrypted tokens.
---
Outside diff comments:
In `@frontend/src/app/api/auth/session/route.ts`:
- Around line 57-70: The frontend is signing session tokens with a payload using
the claim name userId while the backend auth_guard expects user_id; update the
signer used by signSession (and the payload created in frontend's
sessionToken.ts) to emit { user_id, exp } instead of { userId, exp } or add
backward-compatible decoding in signSession so it also sets user_id when only
userId exists, and ensure verifyAuthToken/signSession continue to produce the
cookie name sapling_session with the same maxAge settings so backend(routes
using auth_guard.py) will accept the cookie during rollout.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 01b8fe9a-7972-4263-9df1-4a7b944fcea4

📥 Commits

Reviewing files that changed from the base of the PR and between ba27384 and 43d9015.

📒 Files selected for processing (9)

• backend/routes/auth.py
• backend/routes/documents.py
• backend/routes/flashcards.py
• backend/routes/learn.py
• backend/services/encryption.py
• backend/tests/conftest.py
• backend/tests/test_flashcard_import_routes.py
• frontend/src/app/api/auth/session/route.ts
• frontend/src/middleware.ts

✅ Files skipped from review due to trivial changes (2)

• backend/tests/test_flashcard_import_routes.py
• backend/tests/conftest.py

[coderabbitai]

⚠️ Potential issue | 🟠 Major | 🏗️ Heavy lift

This will orphan pre-existing accounts that don't already have google_id.

When no google_id match exists, the new path always inserts user_{google_id} with is_approved = False. Any existing approved user created before google_id was populated will end up with a second account and lose access to their original courses, documents, graph, and approval state on next sign-in. This needs a transition strategy before merge, such as a one-time backfill of google_id or a temporary legacy-link path that can still find the old row.

[coderabbitai]

⚠️ Potential issue | 🔴 Critical | ⚡ Quick win

Update the calendar token reader in the same rollout.

These writes now persist ciphertext, but backend/routes/calendar.py:35-71 still passes token_row["access_token"] and token_row.get("refresh_token") directly into Credentials(...). After the first successful Google callback, calendar refresh/sync will start using encrypted strings and fail. Please land the matching decrypt-on-read change before shipping this write path.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.
In `@backend/routes/auth.py` around lines 225 - 230, The calendar token reader
must decrypt persisted ciphertext before building the Credentials object: update
the code that constructs Credentials(...) in backend/routes/calendar.py (where
it currently passes token_row["access_token"] and
token_row.get("refresh_token")) to call decrypt on access_token and
decrypt_if_present on refresh_token (or handle None/empty), and convert the
stored expires_at ISO string back to a datetime for expiry; ensure the same
decrypt helper used for encrypt_if_present is referenced so refresh/decode works
after the Google callback writes encrypted tokens.

[AndresL230]

Summary

Adds AES-256-GCM column-level encryption for user PII, OAuth tokens, assignment notes/points, document summaries/concept notes, session summaries, and chat messages. Includes encrypt-on-write + decrypt-on-read across all affected routes, a schema migration that retypes encrypted columns to TEXT, and an idempotent backfill script for existing rows.

Rollout — three things you need to do

1. What to apply to Supabase

Run one SQL file in the Supabase SQL editor: backend/db/migration_encryption_text_columns.sql. It contains four ALTER TABLE ... ALTER COLUMN ... TYPE TEXT USING ::TEXT statements.

Apply it once, before deploying the new code. The casts preserve existing rows as TEXT (e.g., 87.5 becomes the string "87.5"); the decrypt_if_present / decrypt_numeric fallbacks keep those legacy rows readable until you backfill.

2. Values you need to set

Just one new env var. ENCRYPTION_KEY = 64 hex chars (32 bytes). Generate it with:

python -c "import secrets; print(secrets.token_hex(32))"

Set it in:

• backend/.env for local dev (backend/.env.example already has the placeholder + the generation command).
• Wherever your backend actually runs in deploy (Cloudflare Workers/Pages env vars, Vercel, Fly, Railway, whatever — the same place SUPABASE_SERVICE_KEY is set today). docker-compose.yml already passes it through from backend/.env.

Two non-negotiables:

• The same key must be used everywhere your backend runs. Different keys = ciphertext written by one instance is unreadable by another.
• Never rotate or lose this key. Losing it permanently bricks every encrypted column. If you need to rotate, write a script that decrypts with the old key and re-encrypts with the new one in one transaction.

The backend will refuse to boot if ENCRYPTION_KEY is missing, not 64 chars, or not valid hex (intentional fail-fast).

3. The backfill script

backend/db/backfill_encryption.py. For each encrypted column on each table (users.name/email/bio/..., oauth_tokens.access_token/refresh_token, assignments.notes/points_*, documents.summary/concept_notes, sessions.summary_json, messages.content, room_messages.text), it:

1. Selects every row.
2. For each cell, calls decrypt(value) once.
3. If it succeeds → already encrypted → skip.
4. If it raises → the cell is still legacy plaintext → encrypt it and write back.

Prints counts per column. Idempotent — running it a second time changes nothing. Defaults to dry-run (counts only); --apply to actually write. --table users to do it in stages.

How to actually run all of this, in order

# 1. Generate and set the key
python -c "import secrets; print(secrets.token_hex(32))"# paste output as ENCRYPTION_KEY=... in backend/.env# AND set the same value in your deploy environment# 2. Apply the schema migration in Supabase# Dashboard → SQL Editor → paste contents of:# backend/db/migration_encryption_text_columns.sql → Run# 3. Deploy the new backend code (encryption wiring is on this branch)# 4. Backfill — first dry-run to see what will change:cd backend
.\venv\Scripts\python.exe -m db.backfill_encryption
# 5. Then actually apply:
.\venv\Scripts\python.exe -m db.backfill_encryption --apply

After the backfill completes successfully, the decrypt_if_present fallback-to-raw-value warnings should stop appearing in logs. That's the signal it worked.

Test plan

• Apply migration_encryption_text_columns.sql to a Supabase branch DB
• Set ENCRYPTION_KEY (64-hex) and confirm backend boots; confirm it refuses to boot when the var is missing/invalid
• Run backend tests: cd backend && python -m pytest tests/ -q (includes new test_encryption.py)
• Sign in via Google OAuth → confirm users.name/email written as ciphertext, /me returns plaintext
• Upload a document → confirm documents.summary/concept_notes ciphertext at rest, decrypt on library/study-guide/flashcards reads
• Sync calendar → confirm oauth_tokens.access_token/refresh_token and assignments.notes/points_* encrypted
• Send a room message + a learn-session message → confirm room_messages.text and messages.content encrypted
• Run backfill in dry-run on a copy of prod data, verify counts, then --apply and re-run to confirm idempotency (zero changes)
• Confirm decrypt_if_present fallback warnings disappear from logs after backfill

Summary by CodeRabbit

• New Features

  • End-to-end encryption for sensitive data (profiles, documents, sessions, messages, tokens).

• Improvements

  • Decryption in responses and encryption on save for many user-facing flows.
  • Tighter per-request authorization across endpoints and stricter ownership checks.

• Chores

  • Added encryption key configuration and dependency updates; adjusted schema to support encrypted values.

• Tests & Docs

  • Added encryption test coverage and an implementation/rollout plan.

[cloudflare-workers-and-pages]

Deploying with Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Preview URL	Updated (UTC)
✅ Deployment successful! View logs	frontend	43d9015	Commit Preview URL Branch Preview URL	May 03 2026, 07:57 PM

[coderabbitai]

📝 Walkthrough

Walkthrough

Adds AES-256-GCM column-level encryption: new encryption service, test coverage, env/docker wiring, a migration to TEXT for certain columns, a one-shot backfill CLI, and pervasive route changes to encrypt sensitive writes, decrypt reads, and enforce request-based authorization.

Changes

Encryption rollout & route wiring

Layer / File(s)	Summary
Data Shape / Schema Prep backend/db/migration_encryption_text_columns.sql	Retypes specific numeric/JSONB columns to TEXT using USING <col>::TEXT to allow storing ciphertext strings.
Dependencies backend/requirements.txt	Pins cryptography (>=42,<46).
Environment backend/.env.example, docker-compose.yml	Adds ENCRYPTION_KEY placeholder and passes ${ENCRYPTION_KEY} into the backend service.
Encryption Core backend/services/encryption.py	New AES-256-GCM helpers: key loader/validation, encrypt/decrypt, encrypt_if_present/decrypt_if_present, decrypt_numeric, encrypt_json/decrypt_json.
Backfill Tool backend/db/backfill_encryption.py	One-shot CLI that scans configured tables/columns, detects already-encrypted vs legacy plaintext/JSON/numeric values, and optionally writes encrypted values with --apply.
Auth Guard Tightening backend/services/auth_guard.py	get_session_user_id now requires a valid session token (no query-param fallback) and raises 401 on missing/invalid payload.
Route Integration (reads/writes & auth) backend/routes/*.py (auth, onboarding, profile, admin, social, quiz, learn, calendar, gradebook, documents, flashcards, study_guide, graph)	Handlers now accept Request where applicable, enforce require_self/session ownership, encrypt sensitive fields on write and decrypt on read, and narrow SELECT projections. OAuth tokens are decrypted for use and encrypted on refresh/storage. Several patch/allowlist behaviors adjusted to exclude sensitive fields.
Frontend adjustments frontend/src/app/auth/callback/page.tsx, frontend/src/app/api/auth/session/route.ts, frontend/src/middleware.ts	Auth callback no longer requires name param and fetches /api/auth/me from session; session route now requires/verifies authToken; middleware forwards sapling_session cookie to backend auth check.
Tests & Test Setup backend/tests/conftest.py, backend/tests/test_encryption.py, backend/tests/*	Deterministic test key in env, autouse fixture bypasses session auth for route tests, new encryption unit tests (string/JSON/numeric/nonce/tamper), and multiple route test updates to accommodate request-based auth and encrypted fields.
Docs / Plan docs/superpowers/plans/2026-05-03-aes-256-gcm-column-encryption.md	Comprehensive rollout plan, inventory of # ENCRYPTED LATER markers, migration/backfill instructions, and follow-up tasks.

Sequence Diagram

sequenceDiagram
participant Client
participant RouteHandler
participant AuthGuard
participant EncryptionSvc
participant Database
rect rgba(100, 150, 200, 0.5)
Note over Client,Database: Write path (encrypt before persist)
Client->>RouteHandler: POST /api/... (user_id, sensitive)
RouteHandler->>AuthGuard: require_self(user_id, request)
AuthGuard-->>RouteHandler: authorized
RouteHandler->>EncryptionSvc: encrypt(sensitive)
EncryptionSvc-->>RouteHandler: ciphertext
RouteHandler->>Database: INSERT/UPDATE (ciphertext)
Database-->>RouteHandler: OK
RouteHandler-->>Client: 200 (response with decrypted fields)
end
rect rgba(150, 200, 100, 0.5)
Note over Client,Database: Read path (decrypt on load)
Client->>RouteHandler: GET /api/.../{user_id}
RouteHandler->>AuthGuard: require_self(user_id, request)
AuthGuard-->>RouteHandler: authorized
RouteHandler->>Database: SELECT (ciphertext_field)
Database-->>RouteHandler: row with ciphertext
RouteHandler->>EncryptionSvc: decrypt_if_present(ciphertext)
EncryptionSvc-->>RouteHandler: plaintext or legacy value
RouteHandler-->>Client: 200 (plaintext)
end
rect rgba(200, 100, 100, 0.5)
Note over RouteHandler,EncryptionSvc: Legacy plaintext fallback
RouteHandler->>EncryptionSvc: decrypt_if_present(legacy_plaintext)
EncryptionSvc-->>RouteHandler: returns original plaintext (logs warning)
end

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Possibly related PRs

• adding approval gate for closed beta #56: Overlaps changes to backend/routes/auth.py GET /me (authorization and returned fields).
• Course ID schema migration + calendar assignment normalization #53: Overlaps calendar assignment flows and OAuth token handling in backend/routes/calendar.py.
• Frontend revamp (M1-M9 + deferred items + production hardening) #62: Related frontend session handling changes to frontend/src/app/api/auth/session/route.ts (cookie/session verification).

Poem

🐰
I hopped through code at dawn's first light,
Wrapped secrets snug in AES so tight,
Nonces fresh, each byte takes flight,
Now data sleeps secure each night.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 16.56% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'feat: AES-256-GCM column-level encryption for user PII' directly and clearly summarizes the main feature being added—column-level encryption for sensitive user data.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description check	✅ Passed	The PR description comprehensively covers what the PR does, why, rollout steps, environment configuration, backfill instructions, and test plan—all aligned with the description template structure.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/aes-256-gcm-encryption

Tip

💬 Introducing Slack Agent: The best way for teams to turn conversations into code.

Slack Agent is built on CodeRabbit's deep understanding of your code, so your team can collaborate across the entire SDLC without losing context.

• Generate code and open pull requests
• Plan features and break down work
• Investigate incidents and troubleshoot customer tickets together
• Automate recurring tasks and respond to alerts with triggers
• Summarize progress and report instantly

Built for teams:

• Shared memory across your entire org—no repeating context
• Per-thread sandboxes to safely plan and execute work
• Governance built-in—scoped access, auditability, and budget controls

One agent for your entire SDLC. Right inside Slack.

👉 Get started

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 4

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (4)

backend/routes/quiz.py (1)

190-203: ⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Guard student_name against nulls before template replacement.

decrypt_if_present() can return None. If users.name is null, the .replace("{student_name}", student_name) call raises TypeError after the quiz attempt and mastery updates have already been persisted.

Suggested fix

- student_name = decrypt_if_present(user_rows[0]["name"]) if user_rows else "Student"+ student_name = (+ decrypt_if_present(user_rows[0].get("name")) or "Student"+ if user_rows+ else "Student"+ )

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.
In `@backend/routes/quiz.py` around lines 190 - 203, The student_name value used
in the prompt can be None because decrypt_if_present(user_rows[0]["name"]) may
return None; before calling .replace("{student_name}", student_name) ensure
student_name is a non-null string (e.g., coerce to a fallback like "Student" or
"" if None) so template replacement never receives None; update the code around
where student_name is assigned (the decrypt_if_present call and subsequent use
in ctx_prompt/_load_prompt) to coerce or default the value and use that
sanitized variable in the .replace call.

backend/routes/gradebook.py (1)

242-255: ⚠️ Potential issue | 🟠 Major | ⚡ Quick win

Return decrypted fields from create_assignment().

This route now writes encrypted points_possible, points_earned, and notes, then returns inserted[0] verbatim. Any client that uses the POST response to update local state will receive ciphertext instead of the values it just submitted, while the read endpoints return plaintext.

Suggested fix

 inserted = table("assignments").insert({
"id": new_id,
"user_id": body.user_id,
"course_id": body.course_id,
"title": body.title,
"category_id": body.category_id,
"points_possible": encrypt_if_present(body.points_possible),
"points_earned": encrypt_if_present(body.points_earned),
"due_date": body.due_date,
"assignment_type": body.assignment_type,
"notes": encrypt_if_present(body.notes),
"source": "manual",
})
- return {"assignment": inserted[0] if inserted else None}+ assignment = inserted[0] if inserted else None+ if assignment:+ assignment["points_possible"] = decrypt_numeric(assignment.get("points_possible"))+ assignment["points_earned"] = decrypt_numeric(assignment.get("points_earned"))+ assignment["notes"] = decrypt_if_present(assignment.get("notes"))+ return {"assignment": assignment}

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.
In `@backend/routes/gradebook.py` around lines 242 - 255, The POST handler
currently inserts encrypted values (using encrypt_if_present) and returns
inserted[0] as-is, causing ciphertext to be returned; after the insert in
create_assignment (the block that builds inserted =
table("assignments").insert(...)), decrypt the stored fields before returning by
running points_possible, points_earned, and notes through the corresponding
decrypt helper (e.g., decrypt_if_present) and then return the modified
assignment object (rather than the raw inserted[0]); update the return to return
{"assignment": decrypted_assignment} so clients receive plaintext fields
consistent with read endpoints.

backend/routes/learn.py (1)

525-532: ⚠️ Potential issue | 🟠 Major | ⚡ Quick win

Messages returned by resume_session are not decrypted.

When resuming a persisted session, the messages fetched from the database have encrypted content but are returned directly without decryption. This is inconsistent with get_conversation_history which decrypts message content.

🐛 Proposed fix

 msgs = table("messages").select(
"id,role,content,created_at",
filters={"session_id": f"eq.{session_id}"},
order="created_at.asc",
)
+ for m in msgs:+ m["content"] = decrypt_if_present(m.get("content"))
return {
"session": session_rows[0],
"messages": msgs,
}

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.
In `@backend/routes/learn.py` around lines 525 - 532, The messages returned by
resume_session are fetched into msgs via table("messages").select but not
decrypted; update resume_session to reuse the decryption logic from
get_conversation_history (or call get_conversation_history(session_id) instead
of returning raw msgs) so each message's content is decrypted before returning.
Locate the msgs variable and the return that currently returns session_rows[0]
and msgs, then either map over msgs and replace each message's content with the
decrypted value using the same helper used by get_conversation_history, or
delegate to get_conversation_history to produce the decrypted messages, and
return that result.

backend/routes/social.py (1)

343-371: ⚠️ Potential issue | 🟠 Major

user_name is stored unencrypted in room_messages.

The message text is encrypted but body.user_name is stored in plaintext. This is inconsistent with the PR's goal of encrypting PII. User names are PII and should be encrypted at rest.

This also requires updating get_room_messages to decrypt user_name in the message rows (line 290) and reply snippets (line 320).

🔒 Proposed fix to encrypt user_name

 row = table("room_messages").insert({
"room_id": room_id,
"user_id": body.user_id,
- "user_name": body.user_name,+ "user_name": encrypt_if_present(body.user_name),
"text": encrypt_if_present(body.text or None),
"image_url": body.image_url or None,
"reply_to_id": body.reply_to_id or None,
})
if row:
row[0]["text"] = decrypt_if_present(row[0].get("text"))
+ row[0]["user_name"] = decrypt_if_present(row[0].get("user_name"))

In get_room_messages, decrypt user_name when retrieving message rows and reply snippets.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.
In `@backend/routes/social.py` around lines 343 - 371, send_room_message currently
stores body.user_name in plaintext; update the insert in send_room_message to
pass user_name through encrypt_if_present (same pattern as text) so user_name is
encrypted at rest. Then update get_room_messages to call decrypt_if_present on
the message row's user_name and also on any reply snippet user_name (the
reply_to handling at/around where reply snippets are built) to return decrypted
names to clients; preserve null/None handling consistent with
encrypt_if_present/decrypt_if_present usage.

🧹 Nitpick comments (8)

backend/services/auth_guard.py (1)

60-61: 💤 Low value

Add exception chaining for better error tracing.

While catching a broad Exception is acceptable here (any decode failure should yield 401), using raise ... from would preserve the original exception context for debugging.

♻️ Suggested improvement

- except Exception:- raise HTTPException(status_code=401, detail="Not authenticated")+ except Exception as exc:+ raise HTTPException(status_code=401, detail="Not authenticated") from exc

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.
In `@backend/services/auth_guard.py` around lines 60 - 61, The except block
currently swallows the original exception; update the handler in auth_guard.py
so the broad except Exception captures the original exception (e.g., except
Exception as e:) and re-raise the HTTPException with exception chaining (raise
HTTPException(status_code=401, detail="Not authenticated") from e) to preserve
the original traceback for debugging while still returning 401 from the
authentication function/handler.

backend/routes/onboarding.py (1)

14-14: 💤 Low value

Unused request parameter in search_courses.

The request: Request parameter is accepted but never used in this function. If this is intentional for consistency or future auth guards, consider adding a comment. Otherwise, remove it to avoid confusion.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.
In `@backend/routes/onboarding.py` at line 14, The function search_courses
currently declares an unused parameter request: Request which causes confusion;
either remove the request parameter from the function signature of
search_courses (and any corresponding route decorator/handler registration) or,
if it's intentionally reserved for future use (e.g., auth or middleware), add an
inline comment above the signature explaining why request is unused (e.g., "#
request kept for future auth guard") and prefix the variable with an underscore
(request -> _request) to signal intentional non-use. Update any callers or route
mappings that expect the old signature accordingly and ensure imports (Request)
are cleaned up if removed.

backend/db/backfill_encryption.py (2)

91-91: 🏗️ Heavy lift

No pagination — large tables may cause memory/timeout issues.

table(table_name).select(...) on line 91 (and similar calls) loads all rows into memory. For tables with millions of rows (e.g., messages, room_messages), this could exhaust memory or timeout.

Consider adding batching with limit and offset, or using cursor-based pagination:

Example batch approach

BATCH_SIZE=1000offset=0whileTrue:
rows=table(table_name).select(
",".join([pk, *columns]),
limit=BATCH_SIZE,
offset=offset,
order=f"{pk}.asc"
) or []
ifnotrows:
break# process rows...offset+=BATCH_SIZE

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.
In `@backend/db/backfill_encryption.py` at line 91, The current call rows =
table(table_name).select(",".join([pk, *columns])) loads the entire table into
memory; change the logic around table(table_name).select to iterate in batches
(use limit/offset or a cursor) while selecting the same columns (referencing
table_name, pk, columns and the table(...) call) so you fetch e.g. BATCH_SIZE
rows at a time, process them, then advance the offset (or cursor) and repeat
until no rows remain; ensure you preserve ordering (order by pk) to make
pagination deterministic and avoid loading all rows into memory.

---

162-172: 💤 Low value

Corrupt JSON encrypted as raw string may cause decrypt mismatch.

When JSON parsing fails (line 164), the raw string is encrypted via encrypt(v) (line 169). However, reads use decrypt_json() which expects json.loads(decrypt(value)). Decrypting will succeed, but json.loads will fail on the corrupt JSON, triggering the fallback path.

This is acceptable since the fallback handles it, but documenting this behavior would help future maintainers understand why some cells fail JSON parsing after decryption.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.
In `@backend/db/backfill_encryption.py` around lines 162 - 172, When JSON parsing
fails in backfill_encryption.py (the _json.loads(v) exception path), we
currently encrypt the raw string with encrypt(v) so the value can round-trip
through decrypt_if_present/decrypt_json(); add a clear inline comment near the
except block explaining that decrypt_json() will call json.loads(decrypt(value))
and therefore decrypted corrupt JSON will re-trigger the JSON parse fallback at
read time, and that this is intentional because the runtime fallback will handle
it; reference the functions _json.loads, encrypt, decrypt_json, and
decrypt_if_present in the comment so future maintainers understand the
round-trip behavior and why some cells may still fail JSON parsing after
decryption.

frontend/src/app/auth/callback/page.tsx (1)

70-77: 💤 Low value

Silent failure fallback masks /api/auth/me errors.

When the /api/auth/me fetch fails (line 75), the code defaults onboardingCompleted = true, which could incorrectly skip onboarding for users who haven't completed it if the API is temporarily unavailable. Consider logging this case or retrying.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.
In `@frontend/src/app/auth/callback/page.tsx` around lines 70 - 77, The catch
block for the fetch('/api/auth/me') call in page.tsx silently sets
onboardingCompleted = true which can incorrectly skip onboarding on transient
API failures; update the catch to capture the error (e.g., catch (err)), log it
(console.error or your app logger) and set onboardingCompleted conservatively
(false or leave undefined) or implement a simple retry before deciding,
referencing the fetch('/api/auth/me') call and the onboardingCompleted/local
state update to locate the fix.

backend/routes/flashcards.py (1)

128-137: 💤 Low value

Silent pass on decrypt failure is acceptable but consider logging.

The try-except-pass on lines 133-136 silently ignores decryption failures for concept_notes. While this is intentional for legacy plaintext compatibility, the encryption module's docstring mentions "fallback logs a warning." Consider adding a logging statement here for consistency with the stated rollout observability.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.
In `@backend/routes/flashcards.py` around lines 128 - 137, The code silently
swallows exceptions when calling decrypt_json on d.get("concept_notes"); instead
add a warning log inside the except to surface the failure (include context like
the doc id/index and use exc_info=True or log the exception message) while
preserving the fallback behavior of leaving concept_notes unchanged; reference
the decrypt_json call and d["concept_notes"], and ensure you use the module
logger (e.g., obtain logging.getLogger(__name__) or reuse an existing logger
variable) before logging.

backend/routes/learn.py (1)

231-239: ⚡ Quick win

Use explicit None union type annotation.

PEP 484 prohibits implicit Optional. The type hint should use | None for clarity.

♻️ Proposed fix

-def save_message(session_id: str, role: str, content: str, graph_update: dict = None):+def save_message(session_id: str, role: str, content: str, graph_update: dict | None = None):

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.
In `@backend/routes/learn.py` around lines 231 - 239, Update the function
signature for save_message to use an explicit None union type for the
graph_update parameter: replace the implicit Optional style "graph_update: dict
= None" with the explicit union form "graph_update: dict | None = None"
(referencing the save_message function and the graph_update parameter) so the
type hint conforms to PEP 484; ensure no other code changes are required.

backend/tests/test_encryption.py (1)

99-106: Use specific exception type for tamper detection test.

The test currently catches Exception, which is too broad. AES-GCM tamper detection raises cryptography.exceptions.InvalidTag, and using the specific exception type makes the test more precise and prevents accidentally passing if a different exception is raised.

♻️ Proposed fix

 def test_tampered_ciphertext_raises():
import base64
+ from cryptography.exceptions import InvalidTag
ct = encryption.encrypt("secret")
raw = bytearray(base64.b64decode(ct))
raw[-1] ^= 0x01 # flip one bit in the tag
tampered = base64.b64encode(bytes(raw)).decode()
- with pytest.raises(Exception):+ with pytest.raises(InvalidTag):
encryption.decrypt(tampered)

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.
In `@backend/tests/test_encryption.py` around lines 99 - 106, The test
test_tampered_ciphertext_raises should assert the specific AES-GCM tamper
exception instead of catching all Exceptions: import InvalidTag from
cryptography.exceptions and change the context manager to with
pytest.raises(InvalidTag): calling encryption.decrypt(tampered). Keep the rest
of the test (encryption.encrypt and bit-flip tampering) unchanged so it still
exercises tamper detection.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@backend/db/migration_encryption_text_columns.sql`:
- Around line 13-27: The migration casts documents.concept_notes and
sessions.summary_json to TEXT but services/encryption.py's decrypt_json() lacks
the legacy-plaintext fallback, so pre-backfill rows will break; update
decrypt_json() (in backend/services/encryption.py) to detect and return
plaintext JSON when input isn't valid ciphertext (similar to the scalar
fallbacks used by decrypt_text()/decrypt_number()), or alternatively ensure the
DB backfill and enabling of readers are performed atomically so decrypt_json()
never sees legacy plaintext—modify either decrypt_json() to include a JSON
fallback helper or adjust the deployment/migration process to run the backfill
before enabling readers for documents.concept_notes and sessions.summary_json.
In `@backend/routes/auth.py`:
- Around line 228-229: The code is encrypting an empty string when
creds.refresh_token is None (calling encrypt("")), causing inconsistent handling
vs backfilled rows; change the assignment that sets "refresh_token" to either
call encrypt_if_present(creds.refresh_token) or keep a None value when
creds.refresh_token is falsy so empty strings are not encrypted—update the
object construction where "refresh_token" is set (referencing encrypt and
creds.refresh_token) to use encrypt_if_present or conditional preservation of
None to match the backfill behavior.
In `@backend/services/encryption.py`:
- Around line 116-117: decrypt_json currently assumes input is encrypted and
will raise if passed legacy plaintext JSON; update decrypt_json to mirror
decrypt_if_present by attempting to decrypt then json.loads, but on decryption
failure (or if decrypted result is invalid) fall back to json.loads(value) so
pre-encryption JSON still parses; locate the decrypt_json function and wrap its
call to decrypt(value) in a try/except (or check the decrypt result) and use
json.loads(value) as the fallback.
In `@backend/tests/conftest.py`:
- Around line 32-69: The current fixture only monkeypatches already-imported
route modules, leaving services.auth_guard itself untouched and causing
import-order dependent behavior; update the fixture to also monkeypatch the
functions on the services.auth_guard module (replace auth_guard._decode_session
with _decode_session_stub and auth_guard.get_session_user_id,
auth_guard.require_self, auth_guard.require_admin, and auth_guard.require_role
with the corresponding stubs/_require_role_stub) so any later-imported routes
that reference auth_guard will get the bypassed implementations; keep the
existing stubs (_decode_session_stub, _get_session_user_id_stub,
_require_self_stub, _require_admin_stub, _require_role_stub) and use
monkeypatch.setattr(auth_guard, "<name>", <stub>) for each symbol.
---
Outside diff comments:
In `@backend/routes/gradebook.py`:
- Around line 242-255: The POST handler currently inserts encrypted values
(using encrypt_if_present) and returns inserted[0] as-is, causing ciphertext to
be returned; after the insert in create_assignment (the block that builds
inserted = table("assignments").insert(...)), decrypt the stored fields before
returning by running points_possible, points_earned, and notes through the
corresponding decrypt helper (e.g., decrypt_if_present) and then return the
modified assignment object (rather than the raw inserted[0]); update the return
to return {"assignment": decrypted_assignment} so clients receive plaintext
fields consistent with read endpoints.
In `@backend/routes/learn.py`:
- Around line 525-532: The messages returned by resume_session are fetched into
msgs via table("messages").select but not decrypted; update resume_session to
reuse the decryption logic from get_conversation_history (or call
get_conversation_history(session_id) instead of returning raw msgs) so each
message's content is decrypted before returning. Locate the msgs variable and
the return that currently returns session_rows[0] and msgs, then either map over
msgs and replace each message's content with the decrypted value using the same
helper used by get_conversation_history, or delegate to get_conversation_history
to produce the decrypted messages, and return that result.
In `@backend/routes/quiz.py`:
- Around line 190-203: The student_name value used in the prompt can be None
because decrypt_if_present(user_rows[0]["name"]) may return None; before calling
.replace("{student_name}", student_name) ensure student_name is a non-null
string (e.g., coerce to a fallback like "Student" or "" if None) so template
replacement never receives None; update the code around where student_name is
assigned (the decrypt_if_present call and subsequent use in
ctx_prompt/_load_prompt) to coerce or default the value and use that sanitized
variable in the .replace call.
In `@backend/routes/social.py`:
- Around line 343-371: send_room_message currently stores body.user_name in
plaintext; update the insert in send_room_message to pass user_name through
encrypt_if_present (same pattern as text) so user_name is encrypted at rest.
Then update get_room_messages to call decrypt_if_present on the message row's
user_name and also on any reply snippet user_name (the reply_to handling
at/around where reply snippets are built) to return decrypted names to clients;
preserve null/None handling consistent with
encrypt_if_present/decrypt_if_present usage.
---
Nitpick comments:
In `@backend/db/backfill_encryption.py`:
- Line 91: The current call rows = table(table_name).select(",".join([pk,
*columns])) loads the entire table into memory; change the logic around
table(table_name).select to iterate in batches (use limit/offset or a cursor)
while selecting the same columns (referencing table_name, pk, columns and the
table(...) call) so you fetch e.g. BATCH_SIZE rows at a time, process them, then
advance the offset (or cursor) and repeat until no rows remain; ensure you
preserve ordering (order by pk) to make pagination deterministic and avoid
loading all rows into memory.
- Around line 162-172: When JSON parsing fails in backfill_encryption.py (the
_json.loads(v) exception path), we currently encrypt the raw string with
encrypt(v) so the value can round-trip through
decrypt_if_present/decrypt_json(); add a clear inline comment near the except
block explaining that decrypt_json() will call json.loads(decrypt(value)) and
therefore decrypted corrupt JSON will re-trigger the JSON parse fallback at read
time, and that this is intentional because the runtime fallback will handle it;
reference the functions _json.loads, encrypt, decrypt_json, and
decrypt_if_present in the comment so future maintainers understand the
round-trip behavior and why some cells may still fail JSON parsing after
decryption.
In `@backend/routes/flashcards.py`:
- Around line 128-137: The code silently swallows exceptions when calling
decrypt_json on d.get("concept_notes"); instead add a warning log inside the
except to surface the failure (include context like the doc id/index and use
exc_info=True or log the exception message) while preserving the fallback
behavior of leaving concept_notes unchanged; reference the decrypt_json call and
d["concept_notes"], and ensure you use the module logger (e.g., obtain
logging.getLogger(__name__) or reuse an existing logger variable) before
logging.
In `@backend/routes/learn.py`:
- Around line 231-239: Update the function signature for save_message to use an
explicit None union type for the graph_update parameter: replace the implicit
Optional style "graph_update: dict = None" with the explicit union form
"graph_update: dict | None = None" (referencing the save_message function and
the graph_update parameter) so the type hint conforms to PEP 484; ensure no
other code changes are required.
In `@backend/routes/onboarding.py`:
- Line 14: The function search_courses currently declares an unused parameter
request: Request which causes confusion; either remove the request parameter
from the function signature of search_courses (and any corresponding route
decorator/handler registration) or, if it's intentionally reserved for future
use (e.g., auth or middleware), add an inline comment above the signature
explaining why request is unused (e.g., "# request kept for future auth guard")
and prefix the variable with an underscore (request -> _request) to signal
intentional non-use. Update any callers or route mappings that expect the old
signature accordingly and ensure imports (Request) are cleaned up if removed.
In `@backend/services/auth_guard.py`:
- Around line 60-61: The except block currently swallows the original exception;
update the handler in auth_guard.py so the broad except Exception captures the
original exception (e.g., except Exception as e:) and re-raise the HTTPException
with exception chaining (raise HTTPException(status_code=401, detail="Not
authenticated") from e) to preserve the original traceback for debugging while
still returning 401 from the authentication function/handler.
In `@backend/tests/test_encryption.py`:
- Around line 99-106: The test test_tampered_ciphertext_raises should assert the
specific AES-GCM tamper exception instead of catching all Exceptions: import
InvalidTag from cryptography.exceptions and change the context manager to with
pytest.raises(InvalidTag): calling encryption.decrypt(tampered). Keep the rest
of the test (encryption.encrypt and bit-flip tampering) unchanged so it still
exercises tamper detection.
In `@frontend/src/app/auth/callback/page.tsx`:
- Around line 70-77: The catch block for the fetch('/api/auth/me') call in
page.tsx silently sets onboardingCompleted = true which can incorrectly skip
onboarding on transient API failures; update the catch to capture the error
(e.g., catch (err)), log it (console.error or your app logger) and set
onboardingCompleted conservatively (false or leave undefined) or implement a
simple retry before deciding, referencing the fetch('/api/auth/me') call and the
onboardingCompleted/local state update to locate the fix.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 0c1bef18-e8e8-4608-9891-9e17ab2b8476

📥 Commits

Reviewing files that changed from the base of the PR and between 1d184ef and ba27384.

📒 Files selected for processing (29)

• backend/.env.example
• backend/db/backfill_encryption.py
• backend/db/migration_encryption_text_columns.sql
• backend/requirements.txt
• backend/routes/admin.py
• backend/routes/auth.py
• backend/routes/calendar.py
• backend/routes/documents.py
• backend/routes/flashcards.py
• backend/routes/gradebook.py
• backend/routes/graph.py
• backend/routes/learn.py
• backend/routes/onboarding.py
• backend/routes/profile.py
• backend/routes/quiz.py
• backend/routes/social.py
• backend/routes/study_guide.py
• backend/services/auth_guard.py
• backend/services/encryption.py
• backend/tests/conftest.py
• backend/tests/test_encryption.py
• backend/tests/test_flashcard_import_routes.py
• backend/tests/test_learn_routes.py
• backend/tests/test_onboarding_routes.py
• backend/tests/test_shared_course_context.py
• backend/tests/test_social_messages.py
• docker-compose.yml
• docs/superpowers/plans/2026-05-03-aes-256-gcm-column-encryption.md
• frontend/src/app/auth/callback/page.tsx

[AndresL230]

Code review

Found 2 issues:

1. resume_session returns encrypted messages.content to the client without decrypting. save_message now writes encrypt_if_present(content) and get_conversation_history correctly applies decrypt_if_present, but resume_session selects id,role,content,created_at from the messages table and returns the rows as-is — users resuming a session will see base64 ciphertext instead of message text.

Sapling/backend/routes/learn.py

Lines 524 to 533 in ba27384

	msgs=table("messages").select(
	"id,role,content,created_at",
	filters={"session_id": f"eq.{session_id}"},
	order="created_at.asc",
	)
	return {
	"session": session_rows[0],
	"messages": msgs,
	}

2. The /auth/me endpoint signature changed to require a verified session (get_session_user_id(request) — accepts only an auth_token query param or sapling_session cookie), but frontend/src/middleware.ts still calls ${API_URL}/api/auth/me?user_id=... from edge middleware without forwarding either credential. Edge fetch() does not auto-forward browser cookies, so every protected-route navigation will receive 401 Not authenticated and fall into the redirectToSignin(request, 'session_expired') branch — full sign-in regression for approved users. The same ?user_id=... pattern is also used by frontend/src/app/api/auth/session/route.ts (fallback path) and frontend/src/context/UserContext.tsx.

Sapling/frontend/src/middleware.ts

Lines 43 to 62 in ba27384

	if(!API_URL)returnredirectToSignin(request,'google_not_configured')
	try{
	constcontroller=newAbortController()
	consttimeout=setTimeout(()=>controller.abort(),3000)
	letres: Response
	try{
	res=awaitfetch(
	`${API_URL}/api/auth/me?user_id=${encodeURIComponent(session.userId)}`,
	{signal: controller.signal},
	)
	}finally{
	clearTimeout(timeout)
	}
	if(!res.ok)returnredirectToSignin(request,'session_expired')
	constdata=awaitres.json()
	if(data.is_approved!==true)returnNextResponse.redirect(newURL('/pending',request.url))
	}catch{
	returnredirectToSignin(request,'signin_failed')
	}

Sapling/backend/services/auth_guard.py

Lines 16 to 51 in ba27384

	def_decode_session(request: Request) ->dict:
	"""Extract and verify the session token from query params or cookies."""
	token=request.query_params.get("auth_token") orrequest.cookies.get("sapling_session")
	ifnottokenornotSESSION_SECRET:
	raiseHTTPException(status_code=401, detail="Not authenticated")
	parts=token.split(".")
	iflen(parts) !=2:
	raiseHTTPException(status_code=401, detail="Invalid session token")
	payload_b64, sig_b64=parts
	# Verify signature
	expected_sig=_hmac.new(
	SESSION_SECRET.encode(), payload_b64.encode(), hashlib.sha256
	).digest()
	expected_b64=base64.urlsafe_b64encode(expected_sig).decode().rstrip("=")
	ifnot_hmac.compare_digest(sig_b64, expected_b64):
	raiseHTTPException(status_code=401, detail="Invalid session token")
	# Decode payload
	padding=4-len(payload_b64) %4
	ifpadding!=4:
	payload_b64+="="*padding
	try:
	payload=json.loads(base64.urlsafe_b64decode(payload_b64).decode())
	exceptException:
	raiseHTTPException(status_code=401, detail="Invalid session token")
	# Check expiry
	ifpayload.get("exp", 0) <int(_time.time()):
	raiseHTTPException(status_code=401, detail="Session expired")
	returnpayload

🤖 Generated with Claude Code

_{- If this code review was useful, please react with 👍. Otherwise, react with 👎.}

[coderabbitai]

Actionable comments posted: 2

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

frontend/src/app/api/auth/session/route.ts (1)

57-70: ⚠️ Potential issue | 🔴 Critical | 🏗️ Heavy lift

Align the sapling_session payload with backend auth_guard.

This route still mints the browser session through signSession(verifiedUserId), but frontend/src/lib/sessionToken.ts:32-41 signs { userId, exp } while backend/services/auth_guard.py:54-64 looks for payload["user_id"]. After this PR, /api/auth/me and the newly request-authenticated backend routes rely on that cookie, so the frontend will accept the session locally but the backend will 401 it and bounce approved users back to sign-in. Please make both sides read/write the same claim name, ideally with backward-compatible decoding during rollout.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.
In `@frontend/src/app/api/auth/session/route.ts` around lines 57 - 70, The
frontend is signing session tokens with a payload using the claim name userId
while the backend auth_guard expects user_id; update the signer used by
signSession (and the payload created in frontend's sessionToken.ts) to emit {
user_id, exp } instead of { userId, exp } or add backward-compatible decoding in
signSession so it also sets user_id when only userId exists, and ensure
verifyAuthToken/signSession continue to produce the cookie name sapling_session
with the same maxAge settings so backend(routes using auth_guard.py) will accept
the cookie during rollout.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@backend/routes/auth.py`:
- Around line 225-230: The calendar token reader must decrypt persisted
ciphertext before building the Credentials object: update the code that
constructs Credentials(...) in backend/routes/calendar.py (where it currently
passes token_row["access_token"] and token_row.get("refresh_token")) to call
decrypt on access_token and decrypt_if_present on refresh_token (or handle
None/empty), and convert the stored expires_at ISO string back to a datetime for
expiry; ensure the same decrypt helper used for encrypt_if_present is referenced
so refresh/decode works after the Google callback writes encrypted tokens.
---
Outside diff comments:
In `@frontend/src/app/api/auth/session/route.ts`:
- Around line 57-70: The frontend is signing session tokens with a payload using
the claim name userId while the backend auth_guard expects user_id; update the
signer used by signSession (and the payload created in frontend's
sessionToken.ts) to emit { user_id, exp } instead of { userId, exp } or add
backward-compatible decoding in signSession so it also sets user_id when only
userId exists, and ensure verifyAuthToken/signSession continue to produce the
cookie name sapling_session with the same maxAge settings so backend(routes
using auth_guard.py) will accept the cookie during rollout.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 01b8fe9a-7972-4263-9df1-4a7b944fcea4

📥 Commits

Reviewing files that changed from the base of the PR and between ba27384 and 43d9015.

📒 Files selected for processing (9)

• backend/routes/auth.py
• backend/routes/documents.py
• backend/routes/flashcards.py
• backend/routes/learn.py
• backend/services/encryption.py
• backend/tests/conftest.py
• backend/tests/test_flashcard_import_routes.py
• frontend/src/app/api/auth/session/route.ts
• frontend/src/middleware.ts

✅ Files skipped from review due to trivial changes (2)

• backend/tests/test_flashcard_import_routes.py
• backend/tests/conftest.py

[coderabbitai]

⚠️ Potential issue | 🟠 Major | 🏗️ Heavy lift

This will orphan pre-existing accounts that don't already have google_id.

When no google_id match exists, the new path always inserts user_{google_id} with is_approved = False. Any existing approved user created before google_id was populated will end up with a second account and lose access to their original courses, documents, graph, and approval state on next sign-in. This needs a transition strategy before merge, such as a one-time backfill of google_id or a temporary legacy-link path that can still find the old row.

[coderabbitai]

⚠️ Potential issue | 🔴 Critical | ⚡ Quick win

Update the calendar token reader in the same rollout.

These writes now persist ciphertext, but backend/routes/calendar.py:35-71 still passes token_row["access_token"] and token_row.get("refresh_token") directly into Credentials(...). After the first successful Google callback, calendar refresh/sync will start using encrypted strings and fail. Please land the matching decrypt-on-read change before shipping this write path.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.
In `@backend/routes/auth.py` around lines 225 - 230, The calendar token reader
must decrypt persisted ciphertext before building the Credentials object: update
the code that constructs Credentials(...) in backend/routes/calendar.py (where
it currently passes token_row["access_token"] and
token_row.get("refresh_token")) to call decrypt on access_token and
decrypt_if_present on refresh_token (or handle None/empty), and convert the
stored expires_at ISO string back to a datetime for expiry; ensure the same
decrypt helper used for encrypt_if_present is referenced so refresh/decode works
after the Google callback writes encrypted tokens.

[AndresL230]

Summary

Adds AES-256-GCM column-level encryption for user PII, OAuth tokens, assignment notes/points, document summaries/concept notes, session summaries, and chat messages. Includes encrypt-on-write + decrypt-on-read across all affected routes, a schema migration that retypes encrypted columns to TEXT, and an idempotent backfill script for existing rows.

Rollout — three things you need to do

1. What to apply to Supabase

Run one SQL file in the Supabase SQL editor: backend/db/migration_encryption_text_columns.sql. It contains four ALTER TABLE ... ALTER COLUMN ... TYPE TEXT USING ::TEXT statements.

Apply it once, before deploying the new code. The casts preserve existing rows as TEXT (e.g., 87.5 becomes the string "87.5"); the decrypt_if_present / decrypt_numeric fallbacks keep those legacy rows readable until you backfill.

2. Values you need to set

Just one new env var. ENCRYPTION_KEY = 64 hex chars (32 bytes). Generate it with:

python -c "import secrets; print(secrets.token_hex(32))"

Set it in:

• backend/.env for local dev (backend/.env.example already has the placeholder + the generation command).
• Wherever your backend actually runs in deploy (Cloudflare Workers/Pages env vars, Vercel, Fly, Railway, whatever — the same place SUPABASE_SERVICE_KEY is set today). docker-compose.yml already passes it through from backend/.env.

Two non-negotiables:

• The same key must be used everywhere your backend runs. Different keys = ciphertext written by one instance is unreadable by another.
• Never rotate or lose this key. Losing it permanently bricks every encrypted column. If you need to rotate, write a script that decrypts with the old key and re-encrypts with the new one in one transaction.

The backend will refuse to boot if ENCRYPTION_KEY is missing, not 64 chars, or not valid hex (intentional fail-fast).

3. The backfill script

backend/db/backfill_encryption.py. For each encrypted column on each table (users.name/email/bio/..., oauth_tokens.access_token/refresh_token, assignments.notes/points_*, documents.summary/concept_notes, sessions.summary_json, messages.content, room_messages.text), it:

1. Selects every row.
2. For each cell, calls decrypt(value) once.
3. If it succeeds → already encrypted → skip.
4. If it raises → the cell is still legacy plaintext → encrypt it and write back.

Prints counts per column. Idempotent — running it a second time changes nothing. Defaults to dry-run (counts only); --apply to actually write. --table users to do it in stages.

How to actually run all of this, in order

# 1. Generate and set the key
python -c "import secrets; print(secrets.token_hex(32))"# paste output as ENCRYPTION_KEY=... in backend/.env# AND set the same value in your deploy environment# 2. Apply the schema migration in Supabase# Dashboard → SQL Editor → paste contents of:# backend/db/migration_encryption_text_columns.sql → Run# 3. Deploy the new backend code (encryption wiring is on this branch)# 4. Backfill — first dry-run to see what will change:cd backend
.\venv\Scripts\python.exe -m db.backfill_encryption
# 5. Then actually apply:
.\venv\Scripts\python.exe -m db.backfill_encryption --apply

After the backfill completes successfully, the decrypt_if_present fallback-to-raw-value warnings should stop appearing in logs. That's the signal it worked.

Test plan

• Apply migration_encryption_text_columns.sql to a Supabase branch DB
• Set ENCRYPTION_KEY (64-hex) and confirm backend boots; confirm it refuses to boot when the var is missing/invalid
• Run backend tests: cd backend && python -m pytest tests/ -q (includes new test_encryption.py)
• Sign in via Google OAuth → confirm users.name/email written as ciphertext, /me returns plaintext
• Upload a document → confirm documents.summary/concept_notes ciphertext at rest, decrypt on library/study-guide/flashcards reads
• Sync calendar → confirm oauth_tokens.access_token/refresh_token and assignments.notes/points_* encrypted
• Send a room message + a learn-session message → confirm room_messages.text and messages.content encrypted
• Run backfill in dry-run on a copy of prod data, verify counts, then --apply and re-run to confirm idempotency (zero changes)
• Confirm decrypt_if_present fallback warnings disappear from logs after backfill

Summary by CodeRabbit

• New Features

  • End-to-end encryption for sensitive data (profiles, documents, sessions, messages, tokens).

• Improvements

  • Decryption in responses and encryption on save for many user-facing flows.
  • Tighter per-request authorization across endpoints and stricter ownership checks.

• Chores

  • Added encryption key configuration and dependency updates; adjusted schema to support encrypted values.

• Tests & Docs

  • Added encryption test coverage and an implementation/rollout plan.

[cloudflare-workers-and-pages]

Deploying with Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Preview URL	Updated (UTC)
✅ Deployment successful! View logs	frontend	43d9015	Commit Preview URL Branch Preview URL	May 03 2026, 07:57 PM

[coderabbitai]

📝 Walkthrough

Walkthrough

Adds AES-256-GCM column-level encryption: new encryption service, test coverage, env/docker wiring, a migration to TEXT for certain columns, a one-shot backfill CLI, and pervasive route changes to encrypt sensitive writes, decrypt reads, and enforce request-based authorization.

Changes

Encryption rollout & route wiring

Layer / File(s)	Summary
Data Shape / Schema Prep backend/db/migration_encryption_text_columns.sql	Retypes specific numeric/JSONB columns to TEXT using USING <col>::TEXT to allow storing ciphertext strings.
Dependencies backend/requirements.txt	Pins cryptography (>=42,<46).
Environment backend/.env.example, docker-compose.yml	Adds ENCRYPTION_KEY placeholder and passes ${ENCRYPTION_KEY} into the backend service.
Encryption Core backend/services/encryption.py	New AES-256-GCM helpers: key loader/validation, encrypt/decrypt, encrypt_if_present/decrypt_if_present, decrypt_numeric, encrypt_json/decrypt_json.
Backfill Tool backend/db/backfill_encryption.py	One-shot CLI that scans configured tables/columns, detects already-encrypted vs legacy plaintext/JSON/numeric values, and optionally writes encrypted values with --apply.
Auth Guard Tightening backend/services/auth_guard.py	get_session_user_id now requires a valid session token (no query-param fallback) and raises 401 on missing/invalid payload.
Route Integration (reads/writes & auth) backend/routes/*.py (auth, onboarding, profile, admin, social, quiz, learn, calendar, gradebook, documents, flashcards, study_guide, graph)	Handlers now accept Request where applicable, enforce require_self/session ownership, encrypt sensitive fields on write and decrypt on read, and narrow SELECT projections. OAuth tokens are decrypted for use and encrypted on refresh/storage. Several patch/allowlist behaviors adjusted to exclude sensitive fields.
Frontend adjustments frontend/src/app/auth/callback/page.tsx, frontend/src/app/api/auth/session/route.ts, frontend/src/middleware.ts	Auth callback no longer requires name param and fetches /api/auth/me from session; session route now requires/verifies authToken; middleware forwards sapling_session cookie to backend auth check.
Tests & Test Setup backend/tests/conftest.py, backend/tests/test_encryption.py, backend/tests/*	Deterministic test key in env, autouse fixture bypasses session auth for route tests, new encryption unit tests (string/JSON/numeric/nonce/tamper), and multiple route test updates to accommodate request-based auth and encrypted fields.
Docs / Plan docs/superpowers/plans/2026-05-03-aes-256-gcm-column-encryption.md	Comprehensive rollout plan, inventory of # ENCRYPTED LATER markers, migration/backfill instructions, and follow-up tasks.

Sequence Diagram

sequenceDiagram
participant Client
participant RouteHandler
participant AuthGuard
participant EncryptionSvc
participant Database
rect rgba(100, 150, 200, 0.5)
Note over Client,Database: Write path (encrypt before persist)
Client->>RouteHandler: POST /api/... (user_id, sensitive)
RouteHandler->>AuthGuard: require_self(user_id, request)
AuthGuard-->>RouteHandler: authorized
RouteHandler->>EncryptionSvc: encrypt(sensitive)
EncryptionSvc-->>RouteHandler: ciphertext
RouteHandler->>Database: INSERT/UPDATE (ciphertext)
Database-->>RouteHandler: OK
RouteHandler-->>Client: 200 (response with decrypted fields)
end
rect rgba(150, 200, 100, 0.5)
Note over Client,Database: Read path (decrypt on load)
Client->>RouteHandler: GET /api/.../{user_id}
RouteHandler->>AuthGuard: require_self(user_id, request)
AuthGuard-->>RouteHandler: authorized
RouteHandler->>Database: SELECT (ciphertext_field)
Database-->>RouteHandler: row with ciphertext
RouteHandler->>EncryptionSvc: decrypt_if_present(ciphertext)
EncryptionSvc-->>RouteHandler: plaintext or legacy value
RouteHandler-->>Client: 200 (plaintext)
end
rect rgba(200, 100, 100, 0.5)
Note over RouteHandler,EncryptionSvc: Legacy plaintext fallback
RouteHandler->>EncryptionSvc: decrypt_if_present(legacy_plaintext)
EncryptionSvc-->>RouteHandler: returns original plaintext (logs warning)
end

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Possibly related PRs

• adding approval gate for closed beta #56: Overlaps changes to backend/routes/auth.py GET /me (authorization and returned fields).
• Course ID schema migration + calendar assignment normalization #53: Overlaps calendar assignment flows and OAuth token handling in backend/routes/calendar.py.
• Frontend revamp (M1-M9 + deferred items + production hardening) #62: Related frontend session handling changes to frontend/src/app/api/auth/session/route.ts (cookie/session verification).

Poem

🐰
I hopped through code at dawn's first light,
Wrapped secrets snug in AES so tight,
Nonces fresh, each byte takes flight,
Now data sleeps secure each night.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 16.56% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'feat: AES-256-GCM column-level encryption for user PII' directly and clearly summarizes the main feature being added—column-level encryption for sensitive user data.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description check	✅ Passed	The PR description comprehensively covers what the PR does, why, rollout steps, environment configuration, backfill instructions, and test plan—all aligned with the description template structure.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/aes-256-gcm-encryption

Tip

💬 Introducing Slack Agent: The best way for teams to turn conversations into code.

Slack Agent is built on CodeRabbit's deep understanding of your code, so your team can collaborate across the entire SDLC without losing context.

• Generate code and open pull requests
• Plan features and break down work
• Investigate incidents and troubleshoot customer tickets together
• Automate recurring tasks and respond to alerts with triggers
• Summarize progress and report instantly

Built for teams:

• Shared memory across your entire org—no repeating context
• Per-thread sandboxes to safely plan and execute work
• Governance built-in—scoped access, auditability, and budget controls

One agent for your entire SDLC. Right inside Slack.

👉 Get started

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 4

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (4)

backend/routes/quiz.py (1)

190-203: ⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Guard student_name against nulls before template replacement.

decrypt_if_present() can return None. If users.name is null, the .replace("{student_name}", student_name) call raises TypeError after the quiz attempt and mastery updates have already been persisted.

Suggested fix

- student_name = decrypt_if_present(user_rows[0]["name"]) if user_rows else "Student"+ student_name = (+ decrypt_if_present(user_rows[0].get("name")) or "Student"+ if user_rows+ else "Student"+ )

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.
In `@backend/routes/quiz.py` around lines 190 - 203, The student_name value used
in the prompt can be None because decrypt_if_present(user_rows[0]["name"]) may
return None; before calling .replace("{student_name}", student_name) ensure
student_name is a non-null string (e.g., coerce to a fallback like "Student" or
"" if None) so template replacement never receives None; update the code around
where student_name is assigned (the decrypt_if_present call and subsequent use
in ctx_prompt/_load_prompt) to coerce or default the value and use that
sanitized variable in the .replace call.

backend/routes/gradebook.py (1)

242-255: ⚠️ Potential issue | 🟠 Major | ⚡ Quick win

Return decrypted fields from create_assignment().

This route now writes encrypted points_possible, points_earned, and notes, then returns inserted[0] verbatim. Any client that uses the POST response to update local state will receive ciphertext instead of the values it just submitted, while the read endpoints return plaintext.

Suggested fix

 inserted = table("assignments").insert({
"id": new_id,
"user_id": body.user_id,
"course_id": body.course_id,
"title": body.title,
"category_id": body.category_id,
"points_possible": encrypt_if_present(body.points_possible),
"points_earned": encrypt_if_present(body.points_earned),
"due_date": body.due_date,
"assignment_type": body.assignment_type,
"notes": encrypt_if_present(body.notes),
"source": "manual",
})
- return {"assignment": inserted[0] if inserted else None}+ assignment = inserted[0] if inserted else None+ if assignment:+ assignment["points_possible"] = decrypt_numeric(assignment.get("points_possible"))+ assignment["points_earned"] = decrypt_numeric(assignment.get("points_earned"))+ assignment["notes"] = decrypt_if_present(assignment.get("notes"))+ return {"assignment": assignment}

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.
In `@backend/routes/gradebook.py` around lines 242 - 255, The POST handler
currently inserts encrypted values (using encrypt_if_present) and returns
inserted[0] as-is, causing ciphertext to be returned; after the insert in
create_assignment (the block that builds inserted =
table("assignments").insert(...)), decrypt the stored fields before returning by
running points_possible, points_earned, and notes through the corresponding
decrypt helper (e.g., decrypt_if_present) and then return the modified
assignment object (rather than the raw inserted[0]); update the return to return
{"assignment": decrypted_assignment} so clients receive plaintext fields
consistent with read endpoints.

backend/routes/learn.py (1)

525-532: ⚠️ Potential issue | 🟠 Major | ⚡ Quick win

Messages returned by resume_session are not decrypted.

When resuming a persisted session, the messages fetched from the database have encrypted content but are returned directly without decryption. This is inconsistent with get_conversation_history which decrypts message content.

🐛 Proposed fix

 msgs = table("messages").select(
"id,role,content,created_at",
filters={"session_id": f"eq.{session_id}"},
order="created_at.asc",
)
+ for m in msgs:+ m["content"] = decrypt_if_present(m.get("content"))
return {
"session": session_rows[0],
"messages": msgs,
}

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.
In `@backend/routes/learn.py` around lines 525 - 532, The messages returned by
resume_session are fetched into msgs via table("messages").select but not
decrypted; update resume_session to reuse the decryption logic from
get_conversation_history (or call get_conversation_history(session_id) instead
of returning raw msgs) so each message's content is decrypted before returning.
Locate the msgs variable and the return that currently returns session_rows[0]
and msgs, then either map over msgs and replace each message's content with the
decrypted value using the same helper used by get_conversation_history, or
delegate to get_conversation_history to produce the decrypted messages, and
return that result.

backend/routes/social.py (1)

343-371: ⚠️ Potential issue | 🟠 Major

user_name is stored unencrypted in room_messages.

The message text is encrypted but body.user_name is stored in plaintext. This is inconsistent with the PR's goal of encrypting PII. User names are PII and should be encrypted at rest.

This also requires updating get_room_messages to decrypt user_name in the message rows (line 290) and reply snippets (line 320).

🔒 Proposed fix to encrypt user_name

 row = table("room_messages").insert({
"room_id": room_id,
"user_id": body.user_id,
- "user_name": body.user_name,+ "user_name": encrypt_if_present(body.user_name),
"text": encrypt_if_present(body.text or None),
"image_url": body.image_url or None,
"reply_to_id": body.reply_to_id or None,
})
if row:
row[0]["text"] = decrypt_if_present(row[0].get("text"))
+ row[0]["user_name"] = decrypt_if_present(row[0].get("user_name"))

In get_room_messages, decrypt user_name when retrieving message rows and reply snippets.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.
In `@backend/routes/social.py` around lines 343 - 371, send_room_message currently
stores body.user_name in plaintext; update the insert in send_room_message to
pass user_name through encrypt_if_present (same pattern as text) so user_name is
encrypted at rest. Then update get_room_messages to call decrypt_if_present on
the message row's user_name and also on any reply snippet user_name (the
reply_to handling at/around where reply snippets are built) to return decrypted
names to clients; preserve null/None handling consistent with
encrypt_if_present/decrypt_if_present usage.

🧹 Nitpick comments (8)

backend/services/auth_guard.py (1)

60-61: 💤 Low value

Add exception chaining for better error tracing.

While catching a broad Exception is acceptable here (any decode failure should yield 401), using raise ... from would preserve the original exception context for debugging.

♻️ Suggested improvement

- except Exception:- raise HTTPException(status_code=401, detail="Not authenticated")+ except Exception as exc:+ raise HTTPException(status_code=401, detail="Not authenticated") from exc

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.
In `@backend/services/auth_guard.py` around lines 60 - 61, The except block
currently swallows the original exception; update the handler in auth_guard.py
so the broad except Exception captures the original exception (e.g., except
Exception as e:) and re-raise the HTTPException with exception chaining (raise
HTTPException(status_code=401, detail="Not authenticated") from e) to preserve
the original traceback for debugging while still returning 401 from the
authentication function/handler.

backend/routes/onboarding.py (1)

14-14: 💤 Low value

Unused request parameter in search_courses.

The request: Request parameter is accepted but never used in this function. If this is intentional for consistency or future auth guards, consider adding a comment. Otherwise, remove it to avoid confusion.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.
In `@backend/routes/onboarding.py` at line 14, The function search_courses
currently declares an unused parameter request: Request which causes confusion;
either remove the request parameter from the function signature of
search_courses (and any corresponding route decorator/handler registration) or,
if it's intentionally reserved for future use (e.g., auth or middleware), add an
inline comment above the signature explaining why request is unused (e.g., "#
request kept for future auth guard") and prefix the variable with an underscore
(request -> _request) to signal intentional non-use. Update any callers or route
mappings that expect the old signature accordingly and ensure imports (Request)
are cleaned up if removed.

backend/db/backfill_encryption.py (2)

91-91: 🏗️ Heavy lift

No pagination — large tables may cause memory/timeout issues.

table(table_name).select(...) on line 91 (and similar calls) loads all rows into memory. For tables with millions of rows (e.g., messages, room_messages), this could exhaust memory or timeout.

Consider adding batching with limit and offset, or using cursor-based pagination:

Example batch approach

BATCH_SIZE=1000offset=0whileTrue:
rows=table(table_name).select(
",".join([pk, *columns]),
limit=BATCH_SIZE,
offset=offset,
order=f"{pk}.asc"
) or []
ifnotrows:
break# process rows...offset+=BATCH_SIZE

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.
In `@backend/db/backfill_encryption.py` at line 91, The current call rows =
table(table_name).select(",".join([pk, *columns])) loads the entire table into
memory; change the logic around table(table_name).select to iterate in batches
(use limit/offset or a cursor) while selecting the same columns (referencing
table_name, pk, columns and the table(...) call) so you fetch e.g. BATCH_SIZE
rows at a time, process them, then advance the offset (or cursor) and repeat
until no rows remain; ensure you preserve ordering (order by pk) to make
pagination deterministic and avoid loading all rows into memory.

---

162-172: 💤 Low value

Corrupt JSON encrypted as raw string may cause decrypt mismatch.

When JSON parsing fails (line 164), the raw string is encrypted via encrypt(v) (line 169). However, reads use decrypt_json() which expects json.loads(decrypt(value)). Decrypting will succeed, but json.loads will fail on the corrupt JSON, triggering the fallback path.

This is acceptable since the fallback handles it, but documenting this behavior would help future maintainers understand why some cells fail JSON parsing after decryption.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.
In `@backend/db/backfill_encryption.py` around lines 162 - 172, When JSON parsing
fails in backfill_encryption.py (the _json.loads(v) exception path), we
currently encrypt the raw string with encrypt(v) so the value can round-trip
through decrypt_if_present/decrypt_json(); add a clear inline comment near the
except block explaining that decrypt_json() will call json.loads(decrypt(value))
and therefore decrypted corrupt JSON will re-trigger the JSON parse fallback at
read time, and that this is intentional because the runtime fallback will handle
it; reference the functions _json.loads, encrypt, decrypt_json, and
decrypt_if_present in the comment so future maintainers understand the
round-trip behavior and why some cells may still fail JSON parsing after
decryption.

frontend/src/app/auth/callback/page.tsx (1)

70-77: 💤 Low value

Silent failure fallback masks /api/auth/me errors.

When the /api/auth/me fetch fails (line 75), the code defaults onboardingCompleted = true, which could incorrectly skip onboarding for users who haven't completed it if the API is temporarily unavailable. Consider logging this case or retrying.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.
In `@frontend/src/app/auth/callback/page.tsx` around lines 70 - 77, The catch
block for the fetch('/api/auth/me') call in page.tsx silently sets
onboardingCompleted = true which can incorrectly skip onboarding on transient
API failures; update the catch to capture the error (e.g., catch (err)), log it
(console.error or your app logger) and set onboardingCompleted conservatively
(false or leave undefined) or implement a simple retry before deciding,
referencing the fetch('/api/auth/me') call and the onboardingCompleted/local
state update to locate the fix.

backend/routes/flashcards.py (1)

128-137: 💤 Low value

Silent pass on decrypt failure is acceptable but consider logging.

The try-except-pass on lines 133-136 silently ignores decryption failures for concept_notes. While this is intentional for legacy plaintext compatibility, the encryption module's docstring mentions "fallback logs a warning." Consider adding a logging statement here for consistency with the stated rollout observability.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.
In `@backend/routes/flashcards.py` around lines 128 - 137, The code silently
swallows exceptions when calling decrypt_json on d.get("concept_notes"); instead
add a warning log inside the except to surface the failure (include context like
the doc id/index and use exc_info=True or log the exception message) while
preserving the fallback behavior of leaving concept_notes unchanged; reference
the decrypt_json call and d["concept_notes"], and ensure you use the module
logger (e.g., obtain logging.getLogger(__name__) or reuse an existing logger
variable) before logging.

backend/routes/learn.py (1)

231-239: ⚡ Quick win

Use explicit None union type annotation.

PEP 484 prohibits implicit Optional. The type hint should use | None for clarity.

♻️ Proposed fix

-def save_message(session_id: str, role: str, content: str, graph_update: dict = None):+def save_message(session_id: str, role: str, content: str, graph_update: dict | None = None):

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.
In `@backend/routes/learn.py` around lines 231 - 239, Update the function
signature for save_message to use an explicit None union type for the
graph_update parameter: replace the implicit Optional style "graph_update: dict
= None" with the explicit union form "graph_update: dict | None = None"
(referencing the save_message function and the graph_update parameter) so the
type hint conforms to PEP 484; ensure no other code changes are required.

backend/tests/test_encryption.py (1)

99-106: Use specific exception type for tamper detection test.

The test currently catches Exception, which is too broad. AES-GCM tamper detection raises cryptography.exceptions.InvalidTag, and using the specific exception type makes the test more precise and prevents accidentally passing if a different exception is raised.

♻️ Proposed fix

 def test_tampered_ciphertext_raises():
import base64
+ from cryptography.exceptions import InvalidTag
ct = encryption.encrypt("secret")
raw = bytearray(base64.b64decode(ct))
raw[-1] ^= 0x01 # flip one bit in the tag
tampered = base64.b64encode(bytes(raw)).decode()
- with pytest.raises(Exception):+ with pytest.raises(InvalidTag):
encryption.decrypt(tampered)

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.
In `@backend/tests/test_encryption.py` around lines 99 - 106, The test
test_tampered_ciphertext_raises should assert the specific AES-GCM tamper
exception instead of catching all Exceptions: import InvalidTag from
cryptography.exceptions and change the context manager to with
pytest.raises(InvalidTag): calling encryption.decrypt(tampered). Keep the rest
of the test (encryption.encrypt and bit-flip tampering) unchanged so it still
exercises tamper detection.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@backend/db/migration_encryption_text_columns.sql`:
- Around line 13-27: The migration casts documents.concept_notes and
sessions.summary_json to TEXT but services/encryption.py's decrypt_json() lacks
the legacy-plaintext fallback, so pre-backfill rows will break; update
decrypt_json() (in backend/services/encryption.py) to detect and return
plaintext JSON when input isn't valid ciphertext (similar to the scalar
fallbacks used by decrypt_text()/decrypt_number()), or alternatively ensure the
DB backfill and enabling of readers are performed atomically so decrypt_json()
never sees legacy plaintext—modify either decrypt_json() to include a JSON
fallback helper or adjust the deployment/migration process to run the backfill
before enabling readers for documents.concept_notes and sessions.summary_json.
In `@backend/routes/auth.py`:
- Around line 228-229: The code is encrypting an empty string when
creds.refresh_token is None (calling encrypt("")), causing inconsistent handling
vs backfilled rows; change the assignment that sets "refresh_token" to either
call encrypt_if_present(creds.refresh_token) or keep a None value when
creds.refresh_token is falsy so empty strings are not encrypted—update the
object construction where "refresh_token" is set (referencing encrypt and
creds.refresh_token) to use encrypt_if_present or conditional preservation of
None to match the backfill behavior.
In `@backend/services/encryption.py`:
- Around line 116-117: decrypt_json currently assumes input is encrypted and
will raise if passed legacy plaintext JSON; update decrypt_json to mirror
decrypt_if_present by attempting to decrypt then json.loads, but on decryption
failure (or if decrypted result is invalid) fall back to json.loads(value) so
pre-encryption JSON still parses; locate the decrypt_json function and wrap its
call to decrypt(value) in a try/except (or check the decrypt result) and use
json.loads(value) as the fallback.
In `@backend/tests/conftest.py`:
- Around line 32-69: The current fixture only monkeypatches already-imported
route modules, leaving services.auth_guard itself untouched and causing
import-order dependent behavior; update the fixture to also monkeypatch the
functions on the services.auth_guard module (replace auth_guard._decode_session
with _decode_session_stub and auth_guard.get_session_user_id,
auth_guard.require_self, auth_guard.require_admin, and auth_guard.require_role
with the corresponding stubs/_require_role_stub) so any later-imported routes
that reference auth_guard will get the bypassed implementations; keep the
existing stubs (_decode_session_stub, _get_session_user_id_stub,
_require_self_stub, _require_admin_stub, _require_role_stub) and use
monkeypatch.setattr(auth_guard, "<name>", <stub>) for each symbol.
---
Outside diff comments:
In `@backend/routes/gradebook.py`:
- Around line 242-255: The POST handler currently inserts encrypted values
(using encrypt_if_present) and returns inserted[0] as-is, causing ciphertext to
be returned; after the insert in create_assignment (the block that builds
inserted = table("assignments").insert(...)), decrypt the stored fields before
returning by running points_possible, points_earned, and notes through the
corresponding decrypt helper (e.g., decrypt_if_present) and then return the
modified assignment object (rather than the raw inserted[0]); update the return
to return {"assignment": decrypted_assignment} so clients receive plaintext
fields consistent with read endpoints.
In `@backend/routes/learn.py`:
- Around line 525-532: The messages returned by resume_session are fetched into
msgs via table("messages").select but not decrypted; update resume_session to
reuse the decryption logic from get_conversation_history (or call
get_conversation_history(session_id) instead of returning raw msgs) so each
message's content is decrypted before returning. Locate the msgs variable and
the return that currently returns session_rows[0] and msgs, then either map over
msgs and replace each message's content with the decrypted value using the same
helper used by get_conversation_history, or delegate to get_conversation_history
to produce the decrypted messages, and return that result.
In `@backend/routes/quiz.py`:
- Around line 190-203: The student_name value used in the prompt can be None
because decrypt_if_present(user_rows[0]["name"]) may return None; before calling
.replace("{student_name}", student_name) ensure student_name is a non-null
string (e.g., coerce to a fallback like "Student" or "" if None) so template
replacement never receives None; update the code around where student_name is
assigned (the decrypt_if_present call and subsequent use in
ctx_prompt/_load_prompt) to coerce or default the value and use that sanitized
variable in the .replace call.
In `@backend/routes/social.py`:
- Around line 343-371: send_room_message currently stores body.user_name in
plaintext; update the insert in send_room_message to pass user_name through
encrypt_if_present (same pattern as text) so user_name is encrypted at rest.
Then update get_room_messages to call decrypt_if_present on the message row's
user_name and also on any reply snippet user_name (the reply_to handling
at/around where reply snippets are built) to return decrypted names to clients;
preserve null/None handling consistent with
encrypt_if_present/decrypt_if_present usage.
---
Nitpick comments:
In `@backend/db/backfill_encryption.py`:
- Line 91: The current call rows = table(table_name).select(",".join([pk,
*columns])) loads the entire table into memory; change the logic around
table(table_name).select to iterate in batches (use limit/offset or a cursor)
while selecting the same columns (referencing table_name, pk, columns and the
table(...) call) so you fetch e.g. BATCH_SIZE rows at a time, process them, then
advance the offset (or cursor) and repeat until no rows remain; ensure you
preserve ordering (order by pk) to make pagination deterministic and avoid
loading all rows into memory.
- Around line 162-172: When JSON parsing fails in backfill_encryption.py (the
_json.loads(v) exception path), we currently encrypt the raw string with
encrypt(v) so the value can round-trip through
decrypt_if_present/decrypt_json(); add a clear inline comment near the except
block explaining that decrypt_json() will call json.loads(decrypt(value)) and
therefore decrypted corrupt JSON will re-trigger the JSON parse fallback at read
time, and that this is intentional because the runtime fallback will handle it;
reference the functions _json.loads, encrypt, decrypt_json, and
decrypt_if_present in the comment so future maintainers understand the
round-trip behavior and why some cells may still fail JSON parsing after
decryption.
In `@backend/routes/flashcards.py`:
- Around line 128-137: The code silently swallows exceptions when calling
decrypt_json on d.get("concept_notes"); instead add a warning log inside the
except to surface the failure (include context like the doc id/index and use
exc_info=True or log the exception message) while preserving the fallback
behavior of leaving concept_notes unchanged; reference the decrypt_json call and
d["concept_notes"], and ensure you use the module logger (e.g., obtain
logging.getLogger(__name__) or reuse an existing logger variable) before
logging.
In `@backend/routes/learn.py`:
- Around line 231-239: Update the function signature for save_message to use an
explicit None union type for the graph_update parameter: replace the implicit
Optional style "graph_update: dict = None" with the explicit union form
"graph_update: dict | None = None" (referencing the save_message function and
the graph_update parameter) so the type hint conforms to PEP 484; ensure no
other code changes are required.
In `@backend/routes/onboarding.py`:
- Line 14: The function search_courses currently declares an unused parameter
request: Request which causes confusion; either remove the request parameter
from the function signature of search_courses (and any corresponding route
decorator/handler registration) or, if it's intentionally reserved for future
use (e.g., auth or middleware), add an inline comment above the signature
explaining why request is unused (e.g., "# request kept for future auth guard")
and prefix the variable with an underscore (request -> _request) to signal
intentional non-use. Update any callers or route mappings that expect the old
signature accordingly and ensure imports (Request) are cleaned up if removed.
In `@backend/services/auth_guard.py`:
- Around line 60-61: The except block currently swallows the original exception;
update the handler in auth_guard.py so the broad except Exception captures the
original exception (e.g., except Exception as e:) and re-raise the HTTPException
with exception chaining (raise HTTPException(status_code=401, detail="Not
authenticated") from e) to preserve the original traceback for debugging while
still returning 401 from the authentication function/handler.
In `@backend/tests/test_encryption.py`:
- Around line 99-106: The test test_tampered_ciphertext_raises should assert the
specific AES-GCM tamper exception instead of catching all Exceptions: import
InvalidTag from cryptography.exceptions and change the context manager to with
pytest.raises(InvalidTag): calling encryption.decrypt(tampered). Keep the rest
of the test (encryption.encrypt and bit-flip tampering) unchanged so it still
exercises tamper detection.
In `@frontend/src/app/auth/callback/page.tsx`:
- Around line 70-77: The catch block for the fetch('/api/auth/me') call in
page.tsx silently sets onboardingCompleted = true which can incorrectly skip
onboarding on transient API failures; update the catch to capture the error
(e.g., catch (err)), log it (console.error or your app logger) and set
onboardingCompleted conservatively (false or leave undefined) or implement a
simple retry before deciding, referencing the fetch('/api/auth/me') call and the
onboardingCompleted/local state update to locate the fix.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 0c1bef18-e8e8-4608-9891-9e17ab2b8476

📥 Commits

Reviewing files that changed from the base of the PR and between 1d184ef and ba27384.

📒 Files selected for processing (29)

• backend/.env.example
• backend/db/backfill_encryption.py
• backend/db/migration_encryption_text_columns.sql
• backend/requirements.txt
• backend/routes/admin.py
• backend/routes/auth.py
• backend/routes/calendar.py
• backend/routes/documents.py
• backend/routes/flashcards.py
• backend/routes/gradebook.py
• backend/routes/graph.py
• backend/routes/learn.py
• backend/routes/onboarding.py
• backend/routes/profile.py
• backend/routes/quiz.py
• backend/routes/social.py
• backend/routes/study_guide.py
• backend/services/auth_guard.py
• backend/services/encryption.py
• backend/tests/conftest.py
• backend/tests/test_encryption.py
• backend/tests/test_flashcard_import_routes.py
• backend/tests/test_learn_routes.py
• backend/tests/test_onboarding_routes.py
• backend/tests/test_shared_course_context.py
• backend/tests/test_social_messages.py
• docker-compose.yml
• docs/superpowers/plans/2026-05-03-aes-256-gcm-column-encryption.md
• frontend/src/app/auth/callback/page.tsx

[AndresL230]

Code review

Found 2 issues:

1. resume_session returns encrypted messages.content to the client without decrypting. save_message now writes encrypt_if_present(content) and get_conversation_history correctly applies decrypt_if_present, but resume_session selects id,role,content,created_at from the messages table and returns the rows as-is — users resuming a session will see base64 ciphertext instead of message text.

Sapling/backend/routes/learn.py

Lines 524 to 533 in ba27384

	msgs=table("messages").select(
	"id,role,content,created_at",
	filters={"session_id": f"eq.{session_id}"},
	order="created_at.asc",
	)
	return {
	"session": session_rows[0],
	"messages": msgs,
	}

2. The /auth/me endpoint signature changed to require a verified session (get_session_user_id(request) — accepts only an auth_token query param or sapling_session cookie), but frontend/src/middleware.ts still calls ${API_URL}/api/auth/me?user_id=... from edge middleware without forwarding either credential. Edge fetch() does not auto-forward browser cookies, so every protected-route navigation will receive 401 Not authenticated and fall into the redirectToSignin(request, 'session_expired') branch — full sign-in regression for approved users. The same ?user_id=... pattern is also used by frontend/src/app/api/auth/session/route.ts (fallback path) and frontend/src/context/UserContext.tsx.

Sapling/frontend/src/middleware.ts

Lines 43 to 62 in ba27384

	if(!API_URL)returnredirectToSignin(request,'google_not_configured')
	try{
	constcontroller=newAbortController()
	consttimeout=setTimeout(()=>controller.abort(),3000)
	letres: Response
	try{
	res=awaitfetch(
	`${API_URL}/api/auth/me?user_id=${encodeURIComponent(session.userId)}`,
	{signal: controller.signal},
	)
	}finally{
	clearTimeout(timeout)
	}
	if(!res.ok)returnredirectToSignin(request,'session_expired')
	constdata=awaitres.json()
	if(data.is_approved!==true)returnNextResponse.redirect(newURL('/pending',request.url))
	}catch{
	returnredirectToSignin(request,'signin_failed')
	}

Sapling/backend/services/auth_guard.py

Lines 16 to 51 in ba27384

	def_decode_session(request: Request) ->dict:
	"""Extract and verify the session token from query params or cookies."""
	token=request.query_params.get("auth_token") orrequest.cookies.get("sapling_session")
	ifnottokenornotSESSION_SECRET:
	raiseHTTPException(status_code=401, detail="Not authenticated")
	parts=token.split(".")
	iflen(parts) !=2:
	raiseHTTPException(status_code=401, detail="Invalid session token")
	payload_b64, sig_b64=parts
	# Verify signature
	expected_sig=_hmac.new(
	SESSION_SECRET.encode(), payload_b64.encode(), hashlib.sha256
	).digest()
	expected_b64=base64.urlsafe_b64encode(expected_sig).decode().rstrip("=")
	ifnot_hmac.compare_digest(sig_b64, expected_b64):
	raiseHTTPException(status_code=401, detail="Invalid session token")
	# Decode payload
	padding=4-len(payload_b64) %4
	ifpadding!=4:
	payload_b64+="="*padding
	try:
	payload=json.loads(base64.urlsafe_b64decode(payload_b64).decode())
	exceptException:
	raiseHTTPException(status_code=401, detail="Invalid session token")
	# Check expiry
	ifpayload.get("exp", 0) <int(_time.time()):
	raiseHTTPException(status_code=401, detail="Session expired")
	returnpayload

🤖 Generated with Claude Code

_{- If this code review was useful, please react with 👍. Otherwise, react with 👎.}

[coderabbitai]

Actionable comments posted: 2

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

frontend/src/app/api/auth/session/route.ts (1)

57-70: ⚠️ Potential issue | 🔴 Critical | 🏗️ Heavy lift

Align the sapling_session payload with backend auth_guard.

This route still mints the browser session through signSession(verifiedUserId), but frontend/src/lib/sessionToken.ts:32-41 signs { userId, exp } while backend/services/auth_guard.py:54-64 looks for payload["user_id"]. After this PR, /api/auth/me and the newly request-authenticated backend routes rely on that cookie, so the frontend will accept the session locally but the backend will 401 it and bounce approved users back to sign-in. Please make both sides read/write the same claim name, ideally with backward-compatible decoding during rollout.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.
In `@frontend/src/app/api/auth/session/route.ts` around lines 57 - 70, The
frontend is signing session tokens with a payload using the claim name userId
while the backend auth_guard expects user_id; update the signer used by
signSession (and the payload created in frontend's sessionToken.ts) to emit {
user_id, exp } instead of { userId, exp } or add backward-compatible decoding in
signSession so it also sets user_id when only userId exists, and ensure
verifyAuthToken/signSession continue to produce the cookie name sapling_session
with the same maxAge settings so backend(routes using auth_guard.py) will accept
the cookie during rollout.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@backend/routes/auth.py`:
- Around line 225-230: The calendar token reader must decrypt persisted
ciphertext before building the Credentials object: update the code that
constructs Credentials(...) in backend/routes/calendar.py (where it currently
passes token_row["access_token"] and token_row.get("refresh_token")) to call
decrypt on access_token and decrypt_if_present on refresh_token (or handle
None/empty), and convert the stored expires_at ISO string back to a datetime for
expiry; ensure the same decrypt helper used for encrypt_if_present is referenced
so refresh/decode works after the Google callback writes encrypted tokens.
---
Outside diff comments:
In `@frontend/src/app/api/auth/session/route.ts`:
- Around line 57-70: The frontend is signing session tokens with a payload using
the claim name userId while the backend auth_guard expects user_id; update the
signer used by signSession (and the payload created in frontend's
sessionToken.ts) to emit { user_id, exp } instead of { userId, exp } or add
backward-compatible decoding in signSession so it also sets user_id when only
userId exists, and ensure verifyAuthToken/signSession continue to produce the
cookie name sapling_session with the same maxAge settings so backend(routes
using auth_guard.py) will accept the cookie during rollout.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 01b8fe9a-7972-4263-9df1-4a7b944fcea4

📥 Commits

Reviewing files that changed from the base of the PR and between ba27384 and 43d9015.

📒 Files selected for processing (9)

• backend/routes/auth.py
• backend/routes/documents.py
• backend/routes/flashcards.py
• backend/routes/learn.py
• backend/services/encryption.py
• backend/tests/conftest.py
• backend/tests/test_flashcard_import_routes.py
• frontend/src/app/api/auth/session/route.ts
• frontend/src/middleware.ts

✅ Files skipped from review due to trivial changes (2)

• backend/tests/test_flashcard_import_routes.py
• backend/tests/conftest.py

[coderabbitai]

⚠️ Potential issue | 🟠 Major | 🏗️ Heavy lift

This will orphan pre-existing accounts that don't already have google_id.

When no google_id match exists, the new path always inserts user_{google_id} with is_approved = False. Any existing approved user created before google_id was populated will end up with a second account and lose access to their original courses, documents, graph, and approval state on next sign-in. This needs a transition strategy before merge, such as a one-time backfill of google_id or a temporary legacy-link path that can still find the old row.

[coderabbitai]

⚠️ Potential issue | 🔴 Critical | ⚡ Quick win

Update the calendar token reader in the same rollout.

These writes now persist ciphertext, but backend/routes/calendar.py:35-71 still passes token_row["access_token"] and token_row.get("refresh_token") directly into Credentials(...). After the first successful Google callback, calendar refresh/sync will start using encrypted strings and fail. Please land the matching decrypt-on-read change before shipping this write path.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.
In `@backend/routes/auth.py` around lines 225 - 230, The calendar token reader
must decrypt persisted ciphertext before building the Credentials object: update
the code that constructs Credentials(...) in backend/routes/calendar.py (where
it currently passes token_row["access_token"] and
token_row.get("refresh_token")) to call decrypt on access_token and
decrypt_if_present on refresh_token (or handle None/empty), and convert the
stored expires_at ISO string back to a datetime for expiry; ensure the same
decrypt helper used for encrypt_if_present is referenced so refresh/decode works
after the Google callback writes encrypted tokens.

[AndresL230]

Summary

Adds AES-256-GCM column-level encryption for user PII, OAuth tokens, assignment notes/points, document summaries/concept notes, session summaries, and chat messages. Includes encrypt-on-write + decrypt-on-read across all affected routes, a schema migration that retypes encrypted columns to TEXT, and an idempotent backfill script for existing rows.

Rollout — three things you need to do

1. What to apply to Supabase

Run one SQL file in the Supabase SQL editor: backend/db/migration_encryption_text_columns.sql. It contains four ALTER TABLE ... ALTER COLUMN ... TYPE TEXT USING ::TEXT statements.

Apply it once, before deploying the new code. The casts preserve existing rows as TEXT (e.g., 87.5 becomes the string "87.5"); the decrypt_if_present / decrypt_numeric fallbacks keep those legacy rows readable until you backfill.

2. Values you need to set

Just one new env var. ENCRYPTION_KEY = 64 hex chars (32 bytes). Generate it with:

python -c "import secrets; print(secrets.token_hex(32))"

Set it in:

• backend/.env for local dev (backend/.env.example already has the placeholder + the generation command).
• Wherever your backend actually runs in deploy (Cloudflare Workers/Pages env vars, Vercel, Fly, Railway, whatever — the same place SUPABASE_SERVICE_KEY is set today). docker-compose.yml already passes it through from backend/.env.

Two non-negotiables:

• The same key must be used everywhere your backend runs. Different keys = ciphertext written by one instance is unreadable by another.
• Never rotate or lose this key. Losing it permanently bricks every encrypted column. If you need to rotate, write a script that decrypts with the old key and re-encrypts with the new one in one transaction.

The backend will refuse to boot if ENCRYPTION_KEY is missing, not 64 chars, or not valid hex (intentional fail-fast).

3. The backfill script

backend/db/backfill_encryption.py. For each encrypted column on each table (users.name/email/bio/..., oauth_tokens.access_token/refresh_token, assignments.notes/points_*, documents.summary/concept_notes, sessions.summary_json, messages.content, room_messages.text), it:

1. Selects every row.
2. For each cell, calls decrypt(value) once.
3. If it succeeds → already encrypted → skip.
4. If it raises → the cell is still legacy plaintext → encrypt it and write back.

Prints counts per column. Idempotent — running it a second time changes nothing. Defaults to dry-run (counts only); --apply to actually write. --table users to do it in stages.

How to actually run all of this, in order

# 1. Generate and set the key
python -c "import secrets; print(secrets.token_hex(32))"# paste output as ENCRYPTION_KEY=... in backend/.env# AND set the same value in your deploy environment# 2. Apply the schema migration in Supabase# Dashboard → SQL Editor → paste contents of:# backend/db/migration_encryption_text_columns.sql → Run# 3. Deploy the new backend code (encryption wiring is on this branch)# 4. Backfill — first dry-run to see what will change:cd backend
.\venv\Scripts\python.exe -m db.backfill_encryption
# 5. Then actually apply:
.\venv\Scripts\python.exe -m db.backfill_encryption --apply

After the backfill completes successfully, the decrypt_if_present fallback-to-raw-value warnings should stop appearing in logs. That's the signal it worked.

Test plan

• Apply migration_encryption_text_columns.sql to a Supabase branch DB
• Set ENCRYPTION_KEY (64-hex) and confirm backend boots; confirm it refuses to boot when the var is missing/invalid
• Run backend tests: cd backend && python -m pytest tests/ -q (includes new test_encryption.py)
• Sign in via Google OAuth → confirm users.name/email written as ciphertext, /me returns plaintext
• Upload a document → confirm documents.summary/concept_notes ciphertext at rest, decrypt on library/study-guide/flashcards reads
• Sync calendar → confirm oauth_tokens.access_token/refresh_token and assignments.notes/points_* encrypted
• Send a room message + a learn-session message → confirm room_messages.text and messages.content encrypted
• Run backfill in dry-run on a copy of prod data, verify counts, then --apply and re-run to confirm idempotency (zero changes)
• Confirm decrypt_if_present fallback warnings disappear from logs after backfill

Summary by CodeRabbit

• New Features

  • End-to-end encryption for sensitive data (profiles, documents, sessions, messages, tokens).

• Improvements

  • Decryption in responses and encryption on save for many user-facing flows.
  • Tighter per-request authorization across endpoints and stricter ownership checks.

• Chores

  • Added encryption key configuration and dependency updates; adjusted schema to support encrypted values.

• Tests & Docs

  • Added encryption test coverage and an implementation/rollout plan.

[cloudflare-workers-and-pages]

Deploying with Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Preview URL	Updated (UTC)
✅ Deployment successful! View logs	frontend	43d9015	Commit Preview URL Branch Preview URL	May 03 2026, 07:57 PM

[coderabbitai]

📝 Walkthrough

Walkthrough

Adds AES-256-GCM column-level encryption: new encryption service, test coverage, env/docker wiring, a migration to TEXT for certain columns, a one-shot backfill CLI, and pervasive route changes to encrypt sensitive writes, decrypt reads, and enforce request-based authorization.

Changes

Encryption rollout & route wiring

Layer / File(s)	Summary
Data Shape / Schema Prep backend/db/migration_encryption_text_columns.sql	Retypes specific numeric/JSONB columns to TEXT using USING <col>::TEXT to allow storing ciphertext strings.
Dependencies backend/requirements.txt	Pins cryptography (>=42,<46).
Environment backend/.env.example, docker-compose.yml	Adds ENCRYPTION_KEY placeholder and passes ${ENCRYPTION_KEY} into the backend service.
Encryption Core backend/services/encryption.py	New AES-256-GCM helpers: key loader/validation, encrypt/decrypt, encrypt_if_present/decrypt_if_present, decrypt_numeric, encrypt_json/decrypt_json.
Backfill Tool backend/db/backfill_encryption.py	One-shot CLI that scans configured tables/columns, detects already-encrypted vs legacy plaintext/JSON/numeric values, and optionally writes encrypted values with --apply.
Auth Guard Tightening backend/services/auth_guard.py	get_session_user_id now requires a valid session token (no query-param fallback) and raises 401 on missing/invalid payload.
Route Integration (reads/writes & auth) backend/routes/*.py (auth, onboarding, profile, admin, social, quiz, learn, calendar, gradebook, documents, flashcards, study_guide, graph)	Handlers now accept Request where applicable, enforce require_self/session ownership, encrypt sensitive fields on write and decrypt on read, and narrow SELECT projections. OAuth tokens are decrypted for use and encrypted on refresh/storage. Several patch/allowlist behaviors adjusted to exclude sensitive fields.
Frontend adjustments frontend/src/app/auth/callback/page.tsx, frontend/src/app/api/auth/session/route.ts, frontend/src/middleware.ts	Auth callback no longer requires name param and fetches /api/auth/me from session; session route now requires/verifies authToken; middleware forwards sapling_session cookie to backend auth check.
Tests & Test Setup backend/tests/conftest.py, backend/tests/test_encryption.py, backend/tests/*	Deterministic test key in env, autouse fixture bypasses session auth for route tests, new encryption unit tests (string/JSON/numeric/nonce/tamper), and multiple route test updates to accommodate request-based auth and encrypted fields.
Docs / Plan docs/superpowers/plans/2026-05-03-aes-256-gcm-column-encryption.md	Comprehensive rollout plan, inventory of # ENCRYPTED LATER markers, migration/backfill instructions, and follow-up tasks.

Sequence Diagram

sequenceDiagram
participant Client
participant RouteHandler
participant AuthGuard
participant EncryptionSvc
participant Database
rect rgba(100, 150, 200, 0.5)
Note over Client,Database: Write path (encrypt before persist)
Client->>RouteHandler: POST /api/... (user_id, sensitive)
RouteHandler->>AuthGuard: require_self(user_id, request)
AuthGuard-->>RouteHandler: authorized
RouteHandler->>EncryptionSvc: encrypt(sensitive)
EncryptionSvc-->>RouteHandler: ciphertext
RouteHandler->>Database: INSERT/UPDATE (ciphertext)
Database-->>RouteHandler: OK
RouteHandler-->>Client: 200 (response with decrypted fields)
end
rect rgba(150, 200, 100, 0.5)
Note over Client,Database: Read path (decrypt on load)
Client->>RouteHandler: GET /api/.../{user_id}
RouteHandler->>AuthGuard: require_self(user_id, request)
AuthGuard-->>RouteHandler: authorized
RouteHandler->>Database: SELECT (ciphertext_field)
Database-->>RouteHandler: row with ciphertext
RouteHandler->>EncryptionSvc: decrypt_if_present(ciphertext)
EncryptionSvc-->>RouteHandler: plaintext or legacy value
RouteHandler-->>Client: 200 (plaintext)
end
rect rgba(200, 100, 100, 0.5)
Note over RouteHandler,EncryptionSvc: Legacy plaintext fallback
RouteHandler->>EncryptionSvc: decrypt_if_present(legacy_plaintext)
EncryptionSvc-->>RouteHandler: returns original plaintext (logs warning)
end

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Possibly related PRs

• adding approval gate for closed beta #56: Overlaps changes to backend/routes/auth.py GET /me (authorization and returned fields).
• Course ID schema migration + calendar assignment normalization #53: Overlaps calendar assignment flows and OAuth token handling in backend/routes/calendar.py.
• Frontend revamp (M1-M9 + deferred items + production hardening) #62: Related frontend session handling changes to frontend/src/app/api/auth/session/route.ts (cookie/session verification).

Poem

🐰
I hopped through code at dawn's first light,
Wrapped secrets snug in AES so tight,
Nonces fresh, each byte takes flight,
Now data sleeps secure each night.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 16.56% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'feat: AES-256-GCM column-level encryption for user PII' directly and clearly summarizes the main feature being added—column-level encryption for sensitive user data.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description check	✅ Passed	The PR description comprehensively covers what the PR does, why, rollout steps, environment configuration, backfill instructions, and test plan—all aligned with the description template structure.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/aes-256-gcm-encryption

Tip

💬 Introducing Slack Agent: The best way for teams to turn conversations into code.

Slack Agent is built on CodeRabbit's deep understanding of your code, so your team can collaborate across the entire SDLC without losing context.

• Generate code and open pull requests
• Plan features and break down work
• Investigate incidents and troubleshoot customer tickets together
• Automate recurring tasks and respond to alerts with triggers
• Summarize progress and report instantly

Built for teams:

• Shared memory across your entire org—no repeating context
• Per-thread sandboxes to safely plan and execute work
• Governance built-in—scoped access, auditability, and budget controls

One agent for your entire SDLC. Right inside Slack.

👉 Get started

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 4

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (4)

backend/routes/quiz.py (1)

190-203: ⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Guard student_name against nulls before template replacement.

decrypt_if_present() can return None. If users.name is null, the .replace("{student_name}", student_name) call raises TypeError after the quiz attempt and mastery updates have already been persisted.

Suggested fix

- student_name = decrypt_if_present(user_rows[0]["name"]) if user_rows else "Student"+ student_name = (+ decrypt_if_present(user_rows[0].get("name")) or "Student"+ if user_rows+ else "Student"+ )

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.
In `@backend/routes/quiz.py` around lines 190 - 203, The student_name value used
in the prompt can be None because decrypt_if_present(user_rows[0]["name"]) may
return None; before calling .replace("{student_name}", student_name) ensure
student_name is a non-null string (e.g., coerce to a fallback like "Student" or
"" if None) so template replacement never receives None; update the code around
where student_name is assigned (the decrypt_if_present call and subsequent use
in ctx_prompt/_load_prompt) to coerce or default the value and use that
sanitized variable in the .replace call.

backend/routes/gradebook.py (1)

242-255: ⚠️ Potential issue | 🟠 Major | ⚡ Quick win

Return decrypted fields from create_assignment().

This route now writes encrypted points_possible, points_earned, and notes, then returns inserted[0] verbatim. Any client that uses the POST response to update local state will receive ciphertext instead of the values it just submitted, while the read endpoints return plaintext.

Suggested fix

 inserted = table("assignments").insert({
"id": new_id,
"user_id": body.user_id,
"course_id": body.course_id,
"title": body.title,
"category_id": body.category_id,
"points_possible": encrypt_if_present(body.points_possible),
"points_earned": encrypt_if_present(body.points_earned),
"due_date": body.due_date,
"assignment_type": body.assignment_type,
"notes": encrypt_if_present(body.notes),
"source": "manual",
})
- return {"assignment": inserted[0] if inserted else None}+ assignment = inserted[0] if inserted else None+ if assignment:+ assignment["points_possible"] = decrypt_numeric(assignment.get("points_possible"))+ assignment["points_earned"] = decrypt_numeric(assignment.get("points_earned"))+ assignment["notes"] = decrypt_if_present(assignment.get("notes"))+ return {"assignment": assignment}

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.
In `@backend/routes/gradebook.py` around lines 242 - 255, The POST handler
currently inserts encrypted values (using encrypt_if_present) and returns
inserted[0] as-is, causing ciphertext to be returned; after the insert in
create_assignment (the block that builds inserted =
table("assignments").insert(...)), decrypt the stored fields before returning by
running points_possible, points_earned, and notes through the corresponding
decrypt helper (e.g., decrypt_if_present) and then return the modified
assignment object (rather than the raw inserted[0]); update the return to return
{"assignment": decrypted_assignment} so clients receive plaintext fields
consistent with read endpoints.

backend/routes/learn.py (1)

525-532: ⚠️ Potential issue | 🟠 Major | ⚡ Quick win

Messages returned by resume_session are not decrypted.

When resuming a persisted session, the messages fetched from the database have encrypted content but are returned directly without decryption. This is inconsistent with get_conversation_history which decrypts message content.

🐛 Proposed fix

 msgs = table("messages").select(
"id,role,content,created_at",
filters={"session_id": f"eq.{session_id}"},
order="created_at.asc",
)
+ for m in msgs:+ m["content"] = decrypt_if_present(m.get("content"))
return {
"session": session_rows[0],
"messages": msgs,
}

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.
In `@backend/routes/learn.py` around lines 525 - 532, The messages returned by
resume_session are fetched into msgs via table("messages").select but not
decrypted; update resume_session to reuse the decryption logic from
get_conversation_history (or call get_conversation_history(session_id) instead
of returning raw msgs) so each message's content is decrypted before returning.
Locate the msgs variable and the return that currently returns session_rows[0]
and msgs, then either map over msgs and replace each message's content with the
decrypted value using the same helper used by get_conversation_history, or
delegate to get_conversation_history to produce the decrypted messages, and
return that result.

backend/routes/social.py (1)

343-371: ⚠️ Potential issue | 🟠 Major

user_name is stored unencrypted in room_messages.

The message text is encrypted but body.user_name is stored in plaintext. This is inconsistent with the PR's goal of encrypting PII. User names are PII and should be encrypted at rest.

This also requires updating get_room_messages to decrypt user_name in the message rows (line 290) and reply snippets (line 320).

🔒 Proposed fix to encrypt user_name

 row = table("room_messages").insert({
"room_id": room_id,
"user_id": body.user_id,
- "user_name": body.user_name,+ "user_name": encrypt_if_present(body.user_name),
"text": encrypt_if_present(body.text or None),
"image_url": body.image_url or None,
"reply_to_id": body.reply_to_id or None,
})
if row:
row[0]["text"] = decrypt_if_present(row[0].get("text"))
+ row[0]["user_name"] = decrypt_if_present(row[0].get("user_name"))

In get_room_messages, decrypt user_name when retrieving message rows and reply snippets.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.
In `@backend/routes/social.py` around lines 343 - 371, send_room_message currently
stores body.user_name in plaintext; update the insert in send_room_message to
pass user_name through encrypt_if_present (same pattern as text) so user_name is
encrypted at rest. Then update get_room_messages to call decrypt_if_present on
the message row's user_name and also on any reply snippet user_name (the
reply_to handling at/around where reply snippets are built) to return decrypted
names to clients; preserve null/None handling consistent with
encrypt_if_present/decrypt_if_present usage.

🧹 Nitpick comments (8)

backend/services/auth_guard.py (1)

60-61: 💤 Low value

Add exception chaining for better error tracing.

While catching a broad Exception is acceptable here (any decode failure should yield 401), using raise ... from would preserve the original exception context for debugging.

♻️ Suggested improvement

- except Exception:- raise HTTPException(status_code=401, detail="Not authenticated")+ except Exception as exc:+ raise HTTPException(status_code=401, detail="Not authenticated") from exc

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.
In `@backend/services/auth_guard.py` around lines 60 - 61, The except block
currently swallows the original exception; update the handler in auth_guard.py
so the broad except Exception captures the original exception (e.g., except
Exception as e:) and re-raise the HTTPException with exception chaining (raise
HTTPException(status_code=401, detail="Not authenticated") from e) to preserve
the original traceback for debugging while still returning 401 from the
authentication function/handler.

backend/routes/onboarding.py (1)

14-14: 💤 Low value

Unused request parameter in search_courses.

The request: Request parameter is accepted but never used in this function. If this is intentional for consistency or future auth guards, consider adding a comment. Otherwise, remove it to avoid confusion.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.
In `@backend/routes/onboarding.py` at line 14, The function search_courses
currently declares an unused parameter request: Request which causes confusion;
either remove the request parameter from the function signature of
search_courses (and any corresponding route decorator/handler registration) or,
if it's intentionally reserved for future use (e.g., auth or middleware), add an
inline comment above the signature explaining why request is unused (e.g., "#
request kept for future auth guard") and prefix the variable with an underscore
(request -> _request) to signal intentional non-use. Update any callers or route
mappings that expect the old signature accordingly and ensure imports (Request)
are cleaned up if removed.

backend/db/backfill_encryption.py (2)

91-91: 🏗️ Heavy lift

No pagination — large tables may cause memory/timeout issues.

table(table_name).select(...) on line 91 (and similar calls) loads all rows into memory. For tables with millions of rows (e.g., messages, room_messages), this could exhaust memory or timeout.

Consider adding batching with limit and offset, or using cursor-based pagination:

Example batch approach

BATCH_SIZE=1000offset=0whileTrue:
rows=table(table_name).select(
",".join([pk, *columns]),
limit=BATCH_SIZE,
offset=offset,
order=f"{pk}.asc"
) or []
ifnotrows:
break# process rows...offset+=BATCH_SIZE

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.
In `@backend/db/backfill_encryption.py` at line 91, The current call rows =
table(table_name).select(",".join([pk, *columns])) loads the entire table into
memory; change the logic around table(table_name).select to iterate in batches
(use limit/offset or a cursor) while selecting the same columns (referencing
table_name, pk, columns and the table(...) call) so you fetch e.g. BATCH_SIZE
rows at a time, process them, then advance the offset (or cursor) and repeat
until no rows remain; ensure you preserve ordering (order by pk) to make
pagination deterministic and avoid loading all rows into memory.

---

162-172: 💤 Low value

Corrupt JSON encrypted as raw string may cause decrypt mismatch.

When JSON parsing fails (line 164), the raw string is encrypted via encrypt(v) (line 169). However, reads use decrypt_json() which expects json.loads(decrypt(value)). Decrypting will succeed, but json.loads will fail on the corrupt JSON, triggering the fallback path.

This is acceptable since the fallback handles it, but documenting this behavior would help future maintainers understand why some cells fail JSON parsing after decryption.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.
In `@backend/db/backfill_encryption.py` around lines 162 - 172, When JSON parsing
fails in backfill_encryption.py (the _json.loads(v) exception path), we
currently encrypt the raw string with encrypt(v) so the value can round-trip
through decrypt_if_present/decrypt_json(); add a clear inline comment near the
except block explaining that decrypt_json() will call json.loads(decrypt(value))
and therefore decrypted corrupt JSON will re-trigger the JSON parse fallback at
read time, and that this is intentional because the runtime fallback will handle
it; reference the functions _json.loads, encrypt, decrypt_json, and
decrypt_if_present in the comment so future maintainers understand the
round-trip behavior and why some cells may still fail JSON parsing after
decryption.

frontend/src/app/auth/callback/page.tsx (1)

70-77: 💤 Low value

Silent failure fallback masks /api/auth/me errors.

When the /api/auth/me fetch fails (line 75), the code defaults onboardingCompleted = true, which could incorrectly skip onboarding for users who haven't completed it if the API is temporarily unavailable. Consider logging this case or retrying.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.
In `@frontend/src/app/auth/callback/page.tsx` around lines 70 - 77, The catch
block for the fetch('/api/auth/me') call in page.tsx silently sets
onboardingCompleted = true which can incorrectly skip onboarding on transient
API failures; update the catch to capture the error (e.g., catch (err)), log it
(console.error or your app logger) and set onboardingCompleted conservatively
(false or leave undefined) or implement a simple retry before deciding,
referencing the fetch('/api/auth/me') call and the onboardingCompleted/local
state update to locate the fix.

backend/routes/flashcards.py (1)

128-137: 💤 Low value

Silent pass on decrypt failure is acceptable but consider logging.

The try-except-pass on lines 133-136 silently ignores decryption failures for concept_notes. While this is intentional for legacy plaintext compatibility, the encryption module's docstring mentions "fallback logs a warning." Consider adding a logging statement here for consistency with the stated rollout observability.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.
In `@backend/routes/flashcards.py` around lines 128 - 137, The code silently
swallows exceptions when calling decrypt_json on d.get("concept_notes"); instead
add a warning log inside the except to surface the failure (include context like
the doc id/index and use exc_info=True or log the exception message) while
preserving the fallback behavior of leaving concept_notes unchanged; reference
the decrypt_json call and d["concept_notes"], and ensure you use the module
logger (e.g., obtain logging.getLogger(__name__) or reuse an existing logger
variable) before logging.

backend/routes/learn.py (1)

231-239: ⚡ Quick win

Use explicit None union type annotation.

PEP 484 prohibits implicit Optional. The type hint should use | None for clarity.

♻️ Proposed fix

-def save_message(session_id: str, role: str, content: str, graph_update: dict = None):+def save_message(session_id: str, role: str, content: str, graph_update: dict | None = None):

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.
In `@backend/routes/learn.py` around lines 231 - 239, Update the function
signature for save_message to use an explicit None union type for the
graph_update parameter: replace the implicit Optional style "graph_update: dict
= None" with the explicit union form "graph_update: dict | None = None"
(referencing the save_message function and the graph_update parameter) so the
type hint conforms to PEP 484; ensure no other code changes are required.

backend/tests/test_encryption.py (1)

99-106: Use specific exception type for tamper detection test.

The test currently catches Exception, which is too broad. AES-GCM tamper detection raises cryptography.exceptions.InvalidTag, and using the specific exception type makes the test more precise and prevents accidentally passing if a different exception is raised.

♻️ Proposed fix

 def test_tampered_ciphertext_raises():
import base64
+ from cryptography.exceptions import InvalidTag
ct = encryption.encrypt("secret")
raw = bytearray(base64.b64decode(ct))
raw[-1] ^= 0x01 # flip one bit in the tag
tampered = base64.b64encode(bytes(raw)).decode()
- with pytest.raises(Exception):+ with pytest.raises(InvalidTag):
encryption.decrypt(tampered)

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.
In `@backend/tests/test_encryption.py` around lines 99 - 106, The test
test_tampered_ciphertext_raises should assert the specific AES-GCM tamper
exception instead of catching all Exceptions: import InvalidTag from
cryptography.exceptions and change the context manager to with
pytest.raises(InvalidTag): calling encryption.decrypt(tampered). Keep the rest
of the test (encryption.encrypt and bit-flip tampering) unchanged so it still
exercises tamper detection.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@backend/db/migration_encryption_text_columns.sql`:
- Around line 13-27: The migration casts documents.concept_notes and
sessions.summary_json to TEXT but services/encryption.py's decrypt_json() lacks
the legacy-plaintext fallback, so pre-backfill rows will break; update
decrypt_json() (in backend/services/encryption.py) to detect and return
plaintext JSON when input isn't valid ciphertext (similar to the scalar
fallbacks used by decrypt_text()/decrypt_number()), or alternatively ensure the
DB backfill and enabling of readers are performed atomically so decrypt_json()
never sees legacy plaintext—modify either decrypt_json() to include a JSON
fallback helper or adjust the deployment/migration process to run the backfill
before enabling readers for documents.concept_notes and sessions.summary_json.
In `@backend/routes/auth.py`:
- Around line 228-229: The code is encrypting an empty string when
creds.refresh_token is None (calling encrypt("")), causing inconsistent handling
vs backfilled rows; change the assignment that sets "refresh_token" to either
call encrypt_if_present(creds.refresh_token) or keep a None value when
creds.refresh_token is falsy so empty strings are not encrypted—update the
object construction where "refresh_token" is set (referencing encrypt and
creds.refresh_token) to use encrypt_if_present or conditional preservation of
None to match the backfill behavior.
In `@backend/services/encryption.py`:
- Around line 116-117: decrypt_json currently assumes input is encrypted and
will raise if passed legacy plaintext JSON; update decrypt_json to mirror
decrypt_if_present by attempting to decrypt then json.loads, but on decryption
failure (or if decrypted result is invalid) fall back to json.loads(value) so
pre-encryption JSON still parses; locate the decrypt_json function and wrap its
call to decrypt(value) in a try/except (or check the decrypt result) and use
json.loads(value) as the fallback.
In `@backend/tests/conftest.py`:
- Around line 32-69: The current fixture only monkeypatches already-imported
route modules, leaving services.auth_guard itself untouched and causing
import-order dependent behavior; update the fixture to also monkeypatch the
functions on the services.auth_guard module (replace auth_guard._decode_session
with _decode_session_stub and auth_guard.get_session_user_id,
auth_guard.require_self, auth_guard.require_admin, and auth_guard.require_role
with the corresponding stubs/_require_role_stub) so any later-imported routes
that reference auth_guard will get the bypassed implementations; keep the
existing stubs (_decode_session_stub, _get_session_user_id_stub,
_require_self_stub, _require_admin_stub, _require_role_stub) and use
monkeypatch.setattr(auth_guard, "<name>", <stub>) for each symbol.
---
Outside diff comments:
In `@backend/routes/gradebook.py`:
- Around line 242-255: The POST handler currently inserts encrypted values
(using encrypt_if_present) and returns inserted[0] as-is, causing ciphertext to
be returned; after the insert in create_assignment (the block that builds
inserted = table("assignments").insert(...)), decrypt the stored fields before
returning by running points_possible, points_earned, and notes through the
corresponding decrypt helper (e.g., decrypt_if_present) and then return the
modified assignment object (rather than the raw inserted[0]); update the return
to return {"assignment": decrypted_assignment} so clients receive plaintext
fields consistent with read endpoints.
In `@backend/routes/learn.py`:
- Around line 525-532: The messages returned by resume_session are fetched into
msgs via table("messages").select but not decrypted; update resume_session to
reuse the decryption logic from get_conversation_history (or call
get_conversation_history(session_id) instead of returning raw msgs) so each
message's content is decrypted before returning. Locate the msgs variable and
the return that currently returns session_rows[0] and msgs, then either map over
msgs and replace each message's content with the decrypted value using the same
helper used by get_conversation_history, or delegate to get_conversation_history
to produce the decrypted messages, and return that result.
In `@backend/routes/quiz.py`:
- Around line 190-203: The student_name value used in the prompt can be None
because decrypt_if_present(user_rows[0]["name"]) may return None; before calling
.replace("{student_name}", student_name) ensure student_name is a non-null
string (e.g., coerce to a fallback like "Student" or "" if None) so template
replacement never receives None; update the code around where student_name is
assigned (the decrypt_if_present call and subsequent use in
ctx_prompt/_load_prompt) to coerce or default the value and use that sanitized
variable in the .replace call.
In `@backend/routes/social.py`:
- Around line 343-371: send_room_message currently stores body.user_name in
plaintext; update the insert in send_room_message to pass user_name through
encrypt_if_present (same pattern as text) so user_name is encrypted at rest.
Then update get_room_messages to call decrypt_if_present on the message row's
user_name and also on any reply snippet user_name (the reply_to handling
at/around where reply snippets are built) to return decrypted names to clients;
preserve null/None handling consistent with
encrypt_if_present/decrypt_if_present usage.
---
Nitpick comments:
In `@backend/db/backfill_encryption.py`:
- Line 91: The current call rows = table(table_name).select(",".join([pk,
*columns])) loads the entire table into memory; change the logic around
table(table_name).select to iterate in batches (use limit/offset or a cursor)
while selecting the same columns (referencing table_name, pk, columns and the
table(...) call) so you fetch e.g. BATCH_SIZE rows at a time, process them, then
advance the offset (or cursor) and repeat until no rows remain; ensure you
preserve ordering (order by pk) to make pagination deterministic and avoid
loading all rows into memory.
- Around line 162-172: When JSON parsing fails in backfill_encryption.py (the
_json.loads(v) exception path), we currently encrypt the raw string with
encrypt(v) so the value can round-trip through
decrypt_if_present/decrypt_json(); add a clear inline comment near the except
block explaining that decrypt_json() will call json.loads(decrypt(value)) and
therefore decrypted corrupt JSON will re-trigger the JSON parse fallback at read
time, and that this is intentional because the runtime fallback will handle it;
reference the functions _json.loads, encrypt, decrypt_json, and
decrypt_if_present in the comment so future maintainers understand the
round-trip behavior and why some cells may still fail JSON parsing after
decryption.
In `@backend/routes/flashcards.py`:
- Around line 128-137: The code silently swallows exceptions when calling
decrypt_json on d.get("concept_notes"); instead add a warning log inside the
except to surface the failure (include context like the doc id/index and use
exc_info=True or log the exception message) while preserving the fallback
behavior of leaving concept_notes unchanged; reference the decrypt_json call and
d["concept_notes"], and ensure you use the module logger (e.g., obtain
logging.getLogger(__name__) or reuse an existing logger variable) before
logging.
In `@backend/routes/learn.py`:
- Around line 231-239: Update the function signature for save_message to use an
explicit None union type for the graph_update parameter: replace the implicit
Optional style "graph_update: dict = None" with the explicit union form
"graph_update: dict | None = None" (referencing the save_message function and
the graph_update parameter) so the type hint conforms to PEP 484; ensure no
other code changes are required.
In `@backend/routes/onboarding.py`:
- Line 14: The function search_courses currently declares an unused parameter
request: Request which causes confusion; either remove the request parameter
from the function signature of search_courses (and any corresponding route
decorator/handler registration) or, if it's intentionally reserved for future
use (e.g., auth or middleware), add an inline comment above the signature
explaining why request is unused (e.g., "# request kept for future auth guard")
and prefix the variable with an underscore (request -> _request) to signal
intentional non-use. Update any callers or route mappings that expect the old
signature accordingly and ensure imports (Request) are cleaned up if removed.
In `@backend/services/auth_guard.py`:
- Around line 60-61: The except block currently swallows the original exception;
update the handler in auth_guard.py so the broad except Exception captures the
original exception (e.g., except Exception as e:) and re-raise the HTTPException
with exception chaining (raise HTTPException(status_code=401, detail="Not
authenticated") from e) to preserve the original traceback for debugging while
still returning 401 from the authentication function/handler.
In `@backend/tests/test_encryption.py`:
- Around line 99-106: The test test_tampered_ciphertext_raises should assert the
specific AES-GCM tamper exception instead of catching all Exceptions: import
InvalidTag from cryptography.exceptions and change the context manager to with
pytest.raises(InvalidTag): calling encryption.decrypt(tampered). Keep the rest
of the test (encryption.encrypt and bit-flip tampering) unchanged so it still
exercises tamper detection.
In `@frontend/src/app/auth/callback/page.tsx`:
- Around line 70-77: The catch block for the fetch('/api/auth/me') call in
page.tsx silently sets onboardingCompleted = true which can incorrectly skip
onboarding on transient API failures; update the catch to capture the error
(e.g., catch (err)), log it (console.error or your app logger) and set
onboardingCompleted conservatively (false or leave undefined) or implement a
simple retry before deciding, referencing the fetch('/api/auth/me') call and the
onboardingCompleted/local state update to locate the fix.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 0c1bef18-e8e8-4608-9891-9e17ab2b8476

📥 Commits

Reviewing files that changed from the base of the PR and between 1d184ef and ba27384.

📒 Files selected for processing (29)

• backend/.env.example
• backend/db/backfill_encryption.py
• backend/db/migration_encryption_text_columns.sql
• backend/requirements.txt
• backend/routes/admin.py
• backend/routes/auth.py
• backend/routes/calendar.py
• backend/routes/documents.py
• backend/routes/flashcards.py
• backend/routes/gradebook.py
• backend/routes/graph.py
• backend/routes/learn.py
• backend/routes/onboarding.py
• backend/routes/profile.py
• backend/routes/quiz.py
• backend/routes/social.py
• backend/routes/study_guide.py
• backend/services/auth_guard.py
• backend/services/encryption.py
• backend/tests/conftest.py
• backend/tests/test_encryption.py
• backend/tests/test_flashcard_import_routes.py
• backend/tests/test_learn_routes.py
• backend/tests/test_onboarding_routes.py
• backend/tests/test_shared_course_context.py
• backend/tests/test_social_messages.py
• docker-compose.yml
• docs/superpowers/plans/2026-05-03-aes-256-gcm-column-encryption.md
• frontend/src/app/auth/callback/page.tsx

[AndresL230]

Code review

Found 2 issues:

1. resume_session returns encrypted messages.content to the client without decrypting. save_message now writes encrypt_if_present(content) and get_conversation_history correctly applies decrypt_if_present, but resume_session selects id,role,content,created_at from the messages table and returns the rows as-is — users resuming a session will see base64 ciphertext instead of message text.

Sapling/backend/routes/learn.py

Lines 524 to 533 in ba27384

	msgs=table("messages").select(
	"id,role,content,created_at",
	filters={"session_id": f"eq.{session_id}"},
	order="created_at.asc",
	)
	return {
	"session": session_rows[0],
	"messages": msgs,
	}

2. The /auth/me endpoint signature changed to require a verified session (get_session_user_id(request) — accepts only an auth_token query param or sapling_session cookie), but frontend/src/middleware.ts still calls ${API_URL}/api/auth/me?user_id=... from edge middleware without forwarding either credential. Edge fetch() does not auto-forward browser cookies, so every protected-route navigation will receive 401 Not authenticated and fall into the redirectToSignin(request, 'session_expired') branch — full sign-in regression for approved users. The same ?user_id=... pattern is also used by frontend/src/app/api/auth/session/route.ts (fallback path) and frontend/src/context/UserContext.tsx.

Sapling/frontend/src/middleware.ts

Lines 43 to 62 in ba27384

	if(!API_URL)returnredirectToSignin(request,'google_not_configured')
	try{
	constcontroller=newAbortController()
	consttimeout=setTimeout(()=>controller.abort(),3000)
	letres: Response
	try{
	res=awaitfetch(
	`${API_URL}/api/auth/me?user_id=${encodeURIComponent(session.userId)}`,
	{signal: controller.signal},
	)
	}finally{
	clearTimeout(timeout)
	}
	if(!res.ok)returnredirectToSignin(request,'session_expired')
	constdata=awaitres.json()
	if(data.is_approved!==true)returnNextResponse.redirect(newURL('/pending',request.url))
	}catch{
	returnredirectToSignin(request,'signin_failed')
	}

Sapling/backend/services/auth_guard.py

Lines 16 to 51 in ba27384

	def_decode_session(request: Request) ->dict:
	"""Extract and verify the session token from query params or cookies."""
	token=request.query_params.get("auth_token") orrequest.cookies.get("sapling_session")
	ifnottokenornotSESSION_SECRET:
	raiseHTTPException(status_code=401, detail="Not authenticated")
	parts=token.split(".")
	iflen(parts) !=2:
	raiseHTTPException(status_code=401, detail="Invalid session token")
	payload_b64, sig_b64=parts
	# Verify signature
	expected_sig=_hmac.new(
	SESSION_SECRET.encode(), payload_b64.encode(), hashlib.sha256
	).digest()
	expected_b64=base64.urlsafe_b64encode(expected_sig).decode().rstrip("=")
	ifnot_hmac.compare_digest(sig_b64, expected_b64):
	raiseHTTPException(status_code=401, detail="Invalid session token")
	# Decode payload
	padding=4-len(payload_b64) %4
	ifpadding!=4:
	payload_b64+="="*padding
	try:
	payload=json.loads(base64.urlsafe_b64decode(payload_b64).decode())
	exceptException:
	raiseHTTPException(status_code=401, detail="Invalid session token")
	# Check expiry
	ifpayload.get("exp", 0) <int(_time.time()):
	raiseHTTPException(status_code=401, detail="Session expired")
	returnpayload

🤖 Generated with Claude Code

_{- If this code review was useful, please react with 👍. Otherwise, react with 👎.}

[coderabbitai]

Actionable comments posted: 2

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

frontend/src/app/api/auth/session/route.ts (1)

57-70: ⚠️ Potential issue | 🔴 Critical | 🏗️ Heavy lift

Align the sapling_session payload with backend auth_guard.

This route still mints the browser session through signSession(verifiedUserId), but frontend/src/lib/sessionToken.ts:32-41 signs { userId, exp } while backend/services/auth_guard.py:54-64 looks for payload["user_id"]. After this PR, /api/auth/me and the newly request-authenticated backend routes rely on that cookie, so the frontend will accept the session locally but the backend will 401 it and bounce approved users back to sign-in. Please make both sides read/write the same claim name, ideally with backward-compatible decoding during rollout.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.
In `@frontend/src/app/api/auth/session/route.ts` around lines 57 - 70, The
frontend is signing session tokens with a payload using the claim name userId
while the backend auth_guard expects user_id; update the signer used by
signSession (and the payload created in frontend's sessionToken.ts) to emit {
user_id, exp } instead of { userId, exp } or add backward-compatible decoding in
signSession so it also sets user_id when only userId exists, and ensure
verifyAuthToken/signSession continue to produce the cookie name sapling_session
with the same maxAge settings so backend(routes using auth_guard.py) will accept
the cookie during rollout.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@backend/routes/auth.py`:
- Around line 225-230: The calendar token reader must decrypt persisted
ciphertext before building the Credentials object: update the code that
constructs Credentials(...) in backend/routes/calendar.py (where it currently
passes token_row["access_token"] and token_row.get("refresh_token")) to call
decrypt on access_token and decrypt_if_present on refresh_token (or handle
None/empty), and convert the stored expires_at ISO string back to a datetime for
expiry; ensure the same decrypt helper used for encrypt_if_present is referenced
so refresh/decode works after the Google callback writes encrypted tokens.
---
Outside diff comments:
In `@frontend/src/app/api/auth/session/route.ts`:
- Around line 57-70: The frontend is signing session tokens with a payload using
the claim name userId while the backend auth_guard expects user_id; update the
signer used by signSession (and the payload created in frontend's
sessionToken.ts) to emit { user_id, exp } instead of { userId, exp } or add
backward-compatible decoding in signSession so it also sets user_id when only
userId exists, and ensure verifyAuthToken/signSession continue to produce the
cookie name sapling_session with the same maxAge settings so backend(routes
using auth_guard.py) will accept the cookie during rollout.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 01b8fe9a-7972-4263-9df1-4a7b944fcea4

📥 Commits

Reviewing files that changed from the base of the PR and between ba27384 and 43d9015.

📒 Files selected for processing (9)

• backend/routes/auth.py
• backend/routes/documents.py
• backend/routes/flashcards.py
• backend/routes/learn.py
• backend/services/encryption.py
• backend/tests/conftest.py
• backend/tests/test_flashcard_import_routes.py
• frontend/src/app/api/auth/session/route.ts
• frontend/src/middleware.ts

✅ Files skipped from review due to trivial changes (2)

• backend/tests/test_flashcard_import_routes.py
• backend/tests/conftest.py

[coderabbitai]

⚠️ Potential issue | 🟠 Major | 🏗️ Heavy lift

This will orphan pre-existing accounts that don't already have google_id.

When no google_id match exists, the new path always inserts user_{google_id} with is_approved = False. Any existing approved user created before google_id was populated will end up with a second account and lose access to their original courses, documents, graph, and approval state on next sign-in. This needs a transition strategy before merge, such as a one-time backfill of google_id or a temporary legacy-link path that can still find the old row.

[coderabbitai]

⚠️ Potential issue | 🔴 Critical | ⚡ Quick win

Update the calendar token reader in the same rollout.

These writes now persist ciphertext, but backend/routes/calendar.py:35-71 still passes token_row["access_token"] and token_row.get("refresh_token") directly into Credentials(...). After the first successful Google callback, calendar refresh/sync will start using encrypted strings and fail. Please land the matching decrypt-on-read change before shipping this write path.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.
In `@backend/routes/auth.py` around lines 225 - 230, The calendar token reader
must decrypt persisted ciphertext before building the Credentials object: update
the code that constructs Credentials(...) in backend/routes/calendar.py (where
it currently passes token_row["access_token"] and
token_row.get("refresh_token")) to call decrypt on access_token and
decrypt_if_present on refresh_token (or handle None/empty), and convert the
stored expires_at ISO string back to a datetime for expiry; ensure the same
decrypt helper used for encrypt_if_present is referenced so refresh/decode works
after the Google callback writes encrypted tokens.