Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt

Use this file to discover all available pages before exploring further.

​
Executive summary

The highest-risk themes are public edge endpoints that intentionally run with verify_jwt = false, service-role operations that can bypass RLS if org scoping is missed, and third-party webhook trust boundaries that rely on correct signature verification and replay protection. The largest impact areas are cross-tenant data exposure, PHI disclosure through integrations or AI tooling, and integrity compromise of payroll/background-check/telephony workflows. Critical CI controls exist, but supply-chain hardening (for actions and dependency provenance) remains an important residual risk.

​
Scope and assumptions

  • In scope paths:
    • src/ runtime app and auth/session handling
    • supabase/functions/ edge runtime (HTTP functions + shared auth/cors/supabase helpers)
    • supabase/config.toml platform auth and edge JWT-mode settings
    • .github/workflows/build.yml critical CI gate controls
    • vercel.json deployment headers and browser hardening
  • Out of scope:
    • Detailed per-integration protocol audits for every one of the 200+ edge functions
    • Non-critical local tooling behavior (dist/, node_modules/, test fixtures)
    • Infrastructure outside repo (cloud firewall, WAF, secret manager policies)
  • Assumptions:
    • Deployment is internet-exposed production SaaS with PHI and strict tenant isolation requirements.
    • Supabase service-role keys are restricted to server-side functions and never exposed to clients.
    • RLS is the primary tenant isolation boundary for authenticated data access.
    • Third-party integrations (RingCentral, Twilio, Checkr, Plaid, Ramp, Gusto, OpenRouter) are reachable from edge functions.
  • Open questions that could materially change ranking:
    • Is there centralized API gateway/WAF rate limiting in front of Supabase edge endpoints?
    • Are webhook replay windows and nonce caches enforced consistently per provider?
    • Are CI workflows protected by branch protection + required approvals for workflow file changes?

​
System model

​
Primary components

  • Browser SPA (React + react-router) with Supabase session usage and lazy-loaded modules (src/App.tsx).
  • Client auth/session abstraction via useCurrentUser and Supabase JS client (src/platform/auth/useCurrentUser.ts, src/integrations/supabase/client.ts).
  • Supabase Auth + Postgres (RLS + SECURITY DEFINER helper pattern) for tenant isolation (supabase/migrations/20260211182655_6aeefd1c-c5cc-4eaf-98b0-3e38abc7ba6a.sql, tests/rls/pf-profiles.rls.test.ts).
  • Supabase Edge Functions for business and integration workflows (supabase/functions/*, supabase/config.toml).
  • Third-party integrations: telephony/SMS, payroll, financial aggregation, background checks, AI providers (supabase/functions/ringcentral-webhook/index.ts, supabase/functions/sms-webhook/index.ts, supabase/functions/gusto-proxy/index.ts, supabase/functions/plaid-webhook/index.ts, supabase/functions/checkr-webhook/index.ts, supabase/functions/ai-skill-execute/index.ts).
  • CI gate in GitHub Actions before build/test artifact acceptance (.github/workflows/build.yml).

​
Data flows and trust boundaries

  • Internet user browser -> SPA runtime (src/App.tsx)
    • Data: credentials, access tokens, org/site context, UI inputs.
    • Channel: HTTPS browser requests.
    • Security guarantees: route-level auth session checks, React Query caching, error boundary.
    • Validation/enforcement: session lookup and auth state listener (supabase.auth.getSession, supabase.auth.onAuthStateChange).
  • SPA runtime -> Supabase Auth/PostgREST (src/integrations/supabase/client.ts, src/platform/auth/useCurrentUser.ts)
    • Data: JWT bearer token, row-scoped queries, profile/org lookups.
    • Channel: HTTPS via Supabase JS.
    • Security guarantees: JWT auth, RLS-backed data filtering.
    • Validation/enforcement: supabase.auth.getUser() and RLS policies.
  • Internet/webhook providers -> Edge Functions with verify_jwt = false (supabase/config.toml)
    • Data: webhook payloads, provider signatures/JWTs, event metadata.
    • Channel: HTTPS POST webhooks.
    • Security guarantees: function-local signature checks (provider specific) and CORS handling.
    • Validation/enforcement: HMAC/JWT verification in webhook handlers (verifySignature, verifyWebhookSignature, validateTwilioSignature, verifyPlaidWebhook, computeCheckrSignature).
  • Edge Functions -> Postgres with service role (supabase/functions/_shared/supabase.ts)
    • Data: PHI/PII metadata, payroll/banking references, audit events, role assignments.
    • Channel: internal Supabase client over TLS.
    • Security guarantees: elevated service credentials plus explicit org filtering.
    • Validation/enforcement: manual .eq('organization_id', ...) and role checks (verifyOrgAccess, verifyOrgRole).
  • Edge Functions -> External APIs (Checkr/Gusto/Plaid/Ramp/RingCentral/OpenRouter)
    • Data: integration tokens, webhook event payloads, AI prompts/messages.
    • Channel: HTTPS API calls.
    • Security guarantees: provider auth headers, optional encryption at rest for stored tokens.
    • Validation/enforcement: per-provider request signing and error sanitization patterns.
  • GitHub -> CI workflow (.github/workflows/build.yml)
    • Data: source code, dependency graph, test/build outputs.
    • Channel: GitHub-hosted runner execution.
    • Security guarantees: validation steps and smoke gates.
    • Validation/enforcement: format/type/lint/test/RLS coverage/build checks.

​
Diagram

​
Assets and security objectives

AssetWhy it mattersSecurity objective (C/I/A)
Patient and member PHI in CL/PM tablesRegulatory harm (HIPAA/42 CFR Part 2), legal and reputational impactC: High, I: High, A: Medium
Multi-tenant boundaries (organization_id, role assignments)Cross-tenant breach is a platform-level failure modeC: High, I: High
Service-role credentials and integration API secretsCompromise enables privileged data access and workflow tamperingC: High, I: High
Payroll/banking/background-check workflow stateFinancial and compliance-critical integrity of HR/FA operationsI: High, A: High
Telephony/SMS communication records and consent statePrivacy, legal compliance (TCPA), and operational integrityC: High, I: High
AI skill prompts/messages and tool outputsPossible PHI leakage and policy bypass riskC: High, I: Medium
CI pipeline and build artifactsSupply-chain compromise can ship malicious code to productionI: High, A: Medium
Audit and usage logs (pf_audit_logs, pf_ai_usage_logs)Forensics, detection, and compliance evidenceI: High, A: Medium

​
Attacker model

​
Capabilities

  • Remote internet attacker can send arbitrary requests to public endpoints and webhook paths.
  • Attacker can replay captured webhook payload/signature pairs if anti-replay controls are weak.
  • Authenticated low-privilege tenant user can attempt privilege escalation and cross-tenant data access.
  • Third-party integration compromise can send validly signed but maliciously crafted events.
  • Dependency or CI adversary can attempt supply-chain tampering via build pipeline inputs.

​
Non-capabilities

  • Attacker does not have assumed direct shell access to Supabase or Vercel runtime hosts.
  • Attacker does not start with possession of Supabase service-role keys by default.
  • Attacker cannot bypass strong cryptographic signature verification when keys remain secret and implementation is correct.

​
Entry points and attack surfaces

SurfaceHow reachedTrust boundaryNotesEvidence (repo path / symbol)
SPA auth/session bootstrapBrowser load and route navigationInternet -> Browser SPASession restore and auth state drive gated routessrc/App.tsx (supabase.auth.getSession, route guard)
Current-user resolutionAuthenticated browser callsBrowser -> Supabase AuthUses getUser() and query cache for identity statesrc/platform/auth/useCurrentUser.ts (useCurrentUser)
Public edge endpoints (verify_jwt = false)Direct HTTPS requestInternet -> Edge FunctionsMany functions intentionally public and rely on local checkssupabase/config.toml ([functions.*] verify_jwt = false)
Shared edge auth helperInternal function call pathEdge request -> auth helperAccepts Bearer JWT; special service-role token shortcutsupabase/functions/_shared/auth.ts (validateAuth)
CORS policy helperAll edge HTTP responsesBrowser/Webhook -> Edge FunctionsDynamic allowlist + default origins + dev reflection fallbacksupabase/functions/_shared/cors.ts (getCorsHeaders)
RingCentral webhookProvider callbackRingCentral -> Edge FunctionsHMAC-SHA1 signature verification and subscription checkssupabase/functions/ringcentral-webhook/index.ts (verifyWebhookSignature, verifySubscription)
SMS webhook (Twilio/RingCentral)Provider callbackSMS provider -> Edge FunctionsTwilio signature validation, opt-out handling, inbound writessupabase/functions/sms-webhook/index.ts (validateTwilioSignature, handleInboundMessage)
Checkr webhook/session tokenProvider callback + client-initiated token creationCheckr/client -> Edge FunctionsHMAC verification and org-linked credential retrievalsupabase/functions/checkr-webhook/index.ts, supabase/functions/checkr-session-token/index.ts
Plaid/Ramp webhooksProvider callbackPlaid/Ramp -> Edge FunctionsSignature/JWT checks then service-role DB mutationsupabase/functions/plaid-webhook/index.ts, supabase/functions/ramp-webhook/index.ts
AI skill executionClient POSTBrowser -> Edge Functions -> AI providersAuth + org resolution + tool calls + OpenRouter fallbacksupabase/functions/ai-skill-execute/index.ts (validateAuth, runAgenticLoop, callOpenRouterFallback)
Gusto proxyClient POST to proxyBrowser -> Edge Functions -> GustoToken decryption/encryption and proxy header handlingsupabase/functions/gusto-proxy/index.ts (decryptToken, refreshGustoTokens, getClientIp)
CI build workflowPush/PR eventGitHub -> CI runnerValidation and smoke checks before build artifacts.github/workflows/build.yml

​
Top abuse paths

  1. TM-001 Cross-tenant read/write via public edge path
    1. Attacker discovers a verify_jwt = false function lacking complete authz checks.
    2. Sends crafted request with attacker-controlled organization identifiers.
    3. Function executes with service role and missing org filter on one mutation/query.
    4. Data from another tenant is read or modified.
  2. TM-002 Webhook spoofing or replay for privileged workflow mutation
    1. Attacker replays previously valid webhook payload/signature pair.
    2. Endpoint accepts signature but lacks nonce/timestamp replay defense.
    3. Duplicate or stale financial/telephony/background-check state transition is applied.
    4. Integrity and downstream reporting are corrupted.
  3. TM-003 Service-role token misuse in edge auth helper
    1. Service-role key is exposed through misconfiguration/logging/ops leak.
    2. Attacker sends it as Bearer token to validateAuth-using endpoints.
    3. Handler treats requester as internal service-role principal.
    4. Org checks are bypassed where not independently enforced.
  4. TM-004 AI exfiltration of sensitive data through tooling/fallback provider
    1. Authenticated user submits prompts containing PHI or data extraction requests.
    2. Skill executes with tool calls and optional provider fallback.
    3. Sensitive content may transit external provider or tool outputs beyond intended minimum scope.
    4. PHI handling and confidentiality boundaries are weakened.
  5. TM-005 Credential misuse or weak proxy trust assumptions in payroll integration
    1. Attacker abuses endpoint with spoofed proxy headers or compromised account.
    2. Proxy path forwards actions with stored OAuth tokens.
    3. Unauthorized payroll API actions or data access occurs.
    4. Financial integrity and confidentiality are impacted.
  6. TM-006 SMS/telephony ingestion manipulation and consent-state abuse
    1. Attacker submits forged/ambiguous inbound SMS payloads or provider-like callbacks.
    2. Contact matching and status updates mutate communication records.
    3. Consent and message status become inaccurate.
    4. Compliance and patient communication integrity are impacted.
  7. TM-007 CI supply-chain compromise
    1. Malicious dependency update or compromised action behavior enters PR path.
    2. CI executes build/tests with attacker-controlled package code.
    3. Artifact or lockfile integrity is subverted and malicious code reaches deploy path.
    4. Broad confidentiality/integrity impact across all tenants.
  8. TM-008 Resource exhaustion against public edge endpoints
    1. Botnet floods webhook/public function endpoints.
    2. Signature verification and downstream DB/API calls consume compute budget.
    3. Legitimate requests are delayed or dropped.
    4. Availability and SLA degrade across modules.

​
Threat model table

Threat IDThreat sourcePrerequisitesThreat actionImpactImpacted assetsExisting controls (evidence)GapsRecommended mitigationsDetection ideasLikelihoodImpact severityPriority
TM-001External attacker or low-privilege authenticated userAt least one public function or manual-auth path misses complete org/role enforcement. Service-role DB client is reachable in handler logic.Invoke edge function path to read/mutate data for another tenant using crafted org IDs.Cross-tenant confidentiality and integrity breach; potential PHI disclosure.PHI/PII, tenant boundary state, audit trust.RLS baseline + org checks exist (verifyOrgAccess, verifyOrgRole) and many handlers explicitly filter by organization_id (supabase/functions/_shared/auth.ts, supabase/functions/telehealth-create-session/index.ts).verify_jwt = false is broad in config, and control correctness is distributed per function. Manual consistency risk is high.Add centralized middleware enforcing org context + role checks for all non-webhook verify_jwt=false functions; add static policy audit that blocks deploy when required checks are absent.Alert on denied-org access spikes and anomalous cross-org lookup attempts; log normalized caller org + requested org for all privileged handlers.MediumHighhigh
TM-002External attacker, replay attacker, or compromised webhook senderAccess to valid payload/signature pair or weak replay window controls.Replay or forge webhook events to trigger duplicate or stale state transitions.Financial/telephony/background-check workflow corruption and potential unauthorized processing.Financial records, call/message records, HR screening states, audit logs.Signature validation is implemented in multiple handlers (verifyWebhookSignature, computeCheckrSignature, verifySignature, verifyPlaidWebhook, validateTwilioSignature) with timing-safe comparisons in key paths.Replay resistance is not uniformly explicit (nonce/timestamp cache not consistently evident across all webhook handlers).Enforce per-provider replay controls (timestamp tolerance + event-id dedupe store + idempotency TTL) as shared library used by all webhook handlers.Monitor duplicate provider event IDs and signature-fail rates by endpoint; alert on unusual re-delivery bursts.MediumHighhigh
TM-003External attacker with leaked secretService-role key compromise via environment leak, logging, or operational mistake.Use service-role key as Bearer token where validateAuth allows internal service shortcut.Broad authorization bypass at edge layer where additional checks are absent; high blast radius.Service credentials, tenant boundaries, PHI/PII.validateAuth verifies JWT and supports service-role internal mode; many handlers still perform explicit org lookups (supabase/functions/_shared/auth.ts, supabase/functions/ai-skill-execute/index.ts).Service-role shortcut expands blast radius if key leaks; key use is binary and powerful.Remove Bearer service-role shortcut for internet-facing routes; require mTLS/internal network assertion or dedicated signed internal token with narrow claims.Alert on any request authenticated as service-role outside approved internal origins/functions; continuous secret scanning and rotation telemetry.LowHighhigh
TM-004Authenticated insider or compromised tenant accountValid user access to AI skill endpoint and skill/tool availability.Submit PHI-rich prompts or extraction prompts that pass to external provider/tool path, including fallback provider.PHI confidentiality risk, policy/regulatory exposure, unintended data disclosure.PHI-containing prompts, AI outputs, tool-accessible data sets.Auth + org resolution + usage logging + PHI detection warning are present (validateAuth, detectPHI, logUsage) and fallback path is explicit (callOpenRouterFallback).PHI detection appears advisory (warn/log) rather than hard block/redaction; provider fallback may expand data egress surface.Add enforceable PHI policy gate (block/redact before external provider call), skill-level data classification controls, and explicit allow/deny matrix for tool categories by role.Monitor PHI-detection hit rates, provider-fallback usage, and high-volume extraction-like prompt patterns per user/org.MediumHighhigh
TM-005Authenticated attacker with org foothold or header spoofing attemptAccess to proxy endpoint and ability to manipulate request context.Abuse OAuth-backed proxy to perform unauthorized payroll actions or data pulls.Financial data exposure and payroll integrity compromise.OAuth tokens, payroll records, HR data.Token encryption/decryption and refresh logic exist; proxy uses server-injected tokens and client IP handling (gusto-proxy helpers).Trust in forwarded headers can be fragile if edge/network trust boundaries are misconfigured; token misuse detection unclear.Enforce strict trusted-proxy CIDR validation + signed internal forwarding headers; add per-user action authorization checks before proxy forwarding.Alert on anomalous IP/header patterns, repeated refresh failures, and unusual payroll API call volume by org/user.MediumHighhigh
TM-006External attacker or message spoofing actorAccess to SMS callback routes and ability to craft provider-like payload patterns.Trigger inbound/status processing to manipulate consent or communication records.Compliance risk (TCPA/workflow), incorrect outreach state, data integrity loss.SMS consent state, message delivery records, partner/contact linkage.Twilio signature validation and opt-out keyword handling exist; provider format discrimination is implemented (sms-webhook).Multi-provider parsing path can be abused if provider detection is ambiguous; replay/idempotency not clearly universal.Require strict provider-specific endpoint separation or mandatory provider auth artifact per request; add idempotent message/event key enforcement.Alert on opt-out spikes, unknown-provider payload rates, and callback format anomalies.MediumMediummedium
TM-007Supply-chain attacker or compromised dependency ecosystemAbility to influence dependency source or CI execution path.Introduce malicious package/action behavior to alter build outputs.Platform-wide integrity compromise and downstream tenant impact.Build artifacts, deployed SPA/function bundles, secrets in CI context.CI enforces format/type/lint/tests/RLS/build smoke (.github/workflows/build.yml); dependency install uses lockfile (npm ci).Workflow actions are pinned to version tags, not immutable SHAs; provenance/attestation checks are not explicit.Pin GitHub Actions by commit SHA, enable dependency provenance verification, and require CODEOWNERS approval for workflow/lockfile changes.Alert on workflow-file modifications, unexpected lockfile churn, and unusual CI network egress during install/build.MediumHighhigh
TM-008External botnet / opportunistic DoS actorPublic endpoint discoverability and no effective upstream rate limiting.Flood public edge functions and expensive verification/API paths.Reduced availability, delayed workflows, retry storms from providers.Edge compute budget, queue throughput, operational SLAs.Some functions fail fast on signature/auth errors and return early; CI and docs mention rate-limiting recommendations (docs/security/AUTOMATION_SECURITY.md).Explicit global per-endpoint rate limiting and backpressure controls are not evident in repo-level runtime code.Apply gateway-level rate limits + per-provider quotas + circuit breakers on downstream API calls; add bounded queues for webhook processing.Monitor 4xx/5xx ratio, latency percentiles, and retry storm indicators per function/provider.MediumMediummedium

​
Criticality calibration

  • Critical in this repo/context:
    • Any exploit yielding cross-tenant PHI exposure or mutation at scale.
    • Any compromise of service-role credentials enabling broad bypass of tenant controls.
    • CI compromise resulting in malicious code shipped to production.
  • High in this repo/context:
    • Single-tenant PHI exposure through integration or AI data egress.
    • Unauthorized payroll/background-check workflow mutation with financial/compliance consequences.
    • Reliable replay/spoof attacks on webhook-driven state changes.
  • Medium in this repo/context:
    • Availability degradation of public functions without direct confidentiality/integrity loss.
    • Limited-scope consent/message integrity issues requiring multiple conditions.
    • Weak observability that delays detection but does not directly grant access.
  • Low in this repo/context:
    • Informational leakage without tenant crossover or sensitive payload access.
    • Dev-only behavior that is isolated from production paths.
    • Non-exploitable hardening gaps with compensating controls and low attacker utility.
Examples by level:
  • Critical examples: TM-001 at scale with PHI extraction, TM-003 with leaked service-role key, TM-007 with malicious build artifact insertion.
  • High examples: TM-002 replay against financial events, TM-004 PHI egress via AI provider fallback, TM-005 payroll proxy abuse.
  • Medium examples: TM-006 consent-state manipulation with partial impact, TM-008 sustained but bounded endpoint flooding.
  • Low examples: CORS/header hardening deviations without credential-bearing exploit path (none prioritized in top table).

​
Focus paths for security review

PathWhy it mattersRelated Threat IDs
supabase/config.tomlCentral source of verify_jwt posture and auth hardening settings for exposed functions.TM-001, TM-008
supabase/functions/_shared/auth.tsShared auth primitive and service-role shortcut influence many function trust decisions.TM-001, TM-003
supabase/functions/_shared/cors.tsCross-origin policy is centralized and affects all edge endpoints.TM-001, TM-006
supabase/functions/_shared/supabase.tsService-role client creation pattern controls privileged DB access behavior.TM-001, TM-003
supabase/functions/ai-skill-execute/index.tsAI execution path with tools, PHI detection, usage logging, and provider fallback.TM-004
supabase/functions/checkr-webhook/index.tsSignature verification and accepted pre-verification read pattern; high-integrity HR workflow input.TM-002
supabase/functions/checkr-session-token/index.tsCredential brokerage path for Checkr token creation and org access checks.TM-005
supabase/functions/gusto-proxy/index.tsPayroll proxy token handling, trusted header assumptions, and API forwarding behavior.TM-005
supabase/functions/plaid-webhook/index.tsFinancial webhook verification and service-role mutation path.TM-002
supabase/functions/ramp-webhook/index.tsPublic financial webhook endpoint and HMAC verification path.TM-002
supabase/functions/ringcentral-webhook/index.tsTelephony event ingestion with signature verification and subscription validation logic.TM-002, TM-006
supabase/functions/sms-webhook/index.tsMulti-provider SMS callback parsing and consent-related mutation logic.TM-006
src/App.tsxRuntime auth/session gate and provider composition for core app boundaries.TM-001
src/platform/auth/useCurrentUser.tsIdentity state source for frontend authorization assumptions.TM-001
.github/workflows/build.ymlBuild gate and supply-chain attack surface for runtime artifacts.TM-007
vercel.jsonBrowser security headers and deployment-level hardening defaults.TM-001
tests/rls/pf-profiles.rls.test.tsEvidence of tenant/data isolation tests and expected deny behavior.TM-001
supabase/migrations/20260211182655_6aeefd1c-c5cc-4eaf-98b0-3e38abc7ba6a.sqlCanonical RLS enablement and SECURITY DEFINER helper patterns.TM-001, TM-003

​
Quality check

  • Covered discovered entry points: yes (SPA auth, edge API, webhooks, AI endpoint, CI workflow).
  • Covered trust boundaries in threats: yes (internet->edge, edge->DB/service role, edge->vendors, git->CI->deploy).
  • Runtime vs CI/dev separation: explicit in scope/system model and TM-007.
  • User clarifications reflected: yes (whole platform, PHI multi-tenant, runtime + critical CI, top-risk integration deep dive).
  • Assumptions and open questions explicit: yes (scope/assumptions section).