Summary

Let users securely share specific parts of their SymptomSync data with trusted people (caregivers, family, clinicians) for a limited time and with granular scopes (e.g., view meds only, view+edit appointments, view documents but not download). Provide an audit log, easy revocation, and owner notifications on changes. This makes the app more useful in real-world care scenarios while preserving privacy.

Acceptance Criteria

1. Invite Flow

   • From a new Care Circle page, an owner can invite a person by email and select:
     • Role: viewer | editor
     • Scopes: medications, appointments, health_logs, documents, profile
     • Duration: date/time or fixed presets (24h, 7d, 30d, custom)
   • Owner sees a preview of what the invitee will be able to do.

2. Join & Access

   • Invitee receives a magic link (expires in e.g., 24h). On open:
     • If they have a SymptomSync account → accept and join.
     • If not → quick signup → auto-accept invite.
   • Invitee lands on a restricted view limited to granted scopes; non-granted areas are hidden/disabled.

3. Scope Enforcement (RLS)

   • Row Level Security ensures invitees can only select/insert/update/delete rows covered by their grants and role.
   • Access automatically expires when the grant ends; attempts after expiry are denied.

4. Audit & Notifications

   • All invitee actions (create/edit/delete) are logged in an Audit Log visible to the owner.
   • Owner receives in-app notifications (and optional email) on material changes (e.g., med schedule edits).

5. Manage & Revoke

   • Owner can pause, extend, change scopes, or revoke any grant at any time.
   • Revoked users are immediately disconnected from realtime channels.

6. Emergency Access (ICE)

   • Optional ICE code the owner can generate: time-boxed, read-only access to med list + allergies for 1 hour.
   • Owner is notified when ICE is used; ICE is single-use unless regenerated.

7. UX & Compliance

   • Clear badges indicating shared state (e.g., “Shared with 2 caregivers”).
   • Tooltips that explain scopes and privacy implications.
   • No PHI is exposed beyond granted scopes; document downloads respect scope.

Data Model (Supabase)

Tables (new):

• care_circle_members
  • id, owner_id (FK → auth.users), member_user_id (nullable until accept), email, role, status (invited|active|revoked|expired), timestamps
• access_grants
  • id, owner_id, member_id (FK → care_circle_members.id), scopes (string[]), expires_at, created_at
• audit_log
  • id, owner_id, actor_user_id, action (create|update|delete|download), resource_type (medication|appointment|log|document), resource_id, metadata (jsonb), created_at
• ice_tokens
  • id, owner_id, code_hash, expires_at, used_at (nullable), created_at

RLS (illustrative):

• On medication_reminders / appointment_reminders / health_logs / files:
  • select allowed if auth.uid() = user_profile_id OR user has active grant with matching scope AND row belongs to owner_id.
  • insert/update/delete allowed only if grant role = editor and scope allows it.

Endpoints / Functions (examples)

• POST /api/care-circle/invite → create invite & send magic link
• POST /api/care-circle/accept → accept invite (link token)
• GET /api/care-circle → list members & grants
• PUT /api/care-circle/grants/:id → update scopes/expiry/role
• POST /api/care-circle/grants/:id/revoke → revoke access
• GET /api/audit (owner only; filter by resource/date)
• POST /api/ice/generate → returns ICE code (masked); POST /api/ice/use (read-only session)

Implement as Supabase Edge Functions or Next.js API routes; use Supabase Auth for identity and RLS for enforcement.

UI/UX

• Care Circle page: members list, grant chips (scopes), status, actions (extend/revoke).
• Invite modal: email, role, scopes, expiry; inline summary of permissions.
• Restricted UI: hide tabs outside scopes; show “view-only” banners for viewer.
• Audit drawer: chronological activity with filters; export CSV.

Notifications

• In-app toast + bell center for:
  • Invite accepted, grant expiring in 24h, changes by member.
• Optional email digests (daily/weekly).

Security & Privacy

• Magic links are short-lived; verification on accept.
• All PII flows over TLS; tokens stored in HTTP-only cookies.
• Sensitive actions require re-auth (e.g., expanding scope to documents).
• Documents: if scope excludes download, disable presigned URL; allow view-only thumbnails or redact.

Tasks

Backend

• Create tables & indexes; write RLS policies (per table, per scope/role).
• Edge Functions: invite, accept, manage grants, ICE generate/use.
• Triggers to auto-expire grants; write to audit_log on data changes.
• Realtime channel segregation per owner; kick members on revoke.
• Email templates for invites & grant updates.

Frontend

• Care Circle page + invite modal (shadcn/ui).
• Scope picker UI with presets and expiry selector.
• Restricted views & banners; “request broader access” CTA.
• Audit Log drawer with filters & CSV export.
• Notifications center (in-app) + settings.

Quality

• Jest unit tests for grants logic; RLS policy tests via PostgREST RPC.
• Playwright E2E: invite → accept → scoped actions → revoke.
• Accessibility pass (focus states, ARIA, keyboard flows).
• Docs: feature guide, privacy notes, admin override procedure.

Risks & Mitigations

• Over-permissive access: start with conservative defaults; show scope preview; strong RLS tests.
• Invite link leakage: short expiry, one-time tokens, IP/device logging in audit.
• Complex UX: use role presets and scope bundles (“Caregiver basic”, “Clinician read-only”).

Estimated Effort

~2 sprints (MVP without ICE), +0.5 sprint for ICE + audits polish.