Global Clinic Docsv1.0
Back to app
Docs / Developer Documentation

5. Security Documentation

Security spans the edge to the data. The reference build has only a mock client-side auth layer; this section defines the production model. It complements the Architecture security view and the Product compliance section.

1. Authentication architecture

  • Standard. OAuth 2.1 / OpenID Connect. The platform issues short-lived JWT access tokens and longer-lived, rotating refresh tokens. Tokens are signed (asymmetric keys, rotated) and carry the principal, roles, tenant (clinic id) and assigned case ids as claims.
  • Patient sign-in. Email plus password, or email OTP. Accounts verify an email before activation.
  • Staff sign-in. Email plus password with mandatory MFA (TOTP or WebAuthn). Staff sessions require step-up MFA for sensitive actions (escrow release, role changes, Country-Pack publish).
  • Clinic sign-in. Per-user accounts within a clinic tenant; MFA required.
  • Sessions. Refresh-token rotation with reuse detection; server-side revocation on logout; idle and absolute session lifetimes; device and session listing.
  • Reset and recovery. Single-use, time-boxed reset tokens; rate-limited OTP with lockout and backoff; no account enumeration (uniform responses).
  • Reference build note. lib/auth.tsx is a client-only mock with two demo accounts persisted to localStorage. It validates the AuthUser shape and useAuth() contract that the real provider will keep, but it is not a security control and must be replaced.

2. Authorization model

Authorization is deny by default and enforced server-side on every request, never in the client. A request is allowed only if all of the following hold: the token is valid and unexpired; the role permits the operation; and the target is within the caller's tenant and case scope.

flowchart TD
  REQ[Request + access token] --> A{Token valid?}
  A -- No --> D401[401]
  A -- Yes --> B{Role permits operation?}
  B -- No --> D403[403]
  B -- Yes --> C{In tenant + case scope?}
  C -- No --> D403
  C -- Yes --> OK[Authorized -> handler]

3. Authorization and RBAC

The roles and what each may reach are defined in the Product RBAC matrix. The technical model:

  • Roles are coarse capabilities (patient, coordinator, specialist, provider, visa, travel, finance, admin, agent, medical director, support).
  • Scopes narrow a role to a tenant and to assigned cases. A clinic user is scoped to clinicId; a coordinator to assigned caseIds; a patient to their own caseId.
  • Permissions are checked per endpoint and per field. Sensitive fields (financial account details, full medical records) carry field-level checks within a role.
  • Tenant isolation is enforced at the data layer with PostgreSQL row-level security: every tenant-owned table carries clinicId and/or caseId, and a policy restricts rows to the caller's scope, so even a flawed query cannot cross tenants.
  • Consent-gated support. Support access to a patient case requires an active patient consent grant and is fully audited.
  • Break-glass. Emergency clinical access (for a complication) is possible for authorised roles but is alarmed, time-boxed, and audited after the fact.

4. Data encryption requirements

  • In transit. TLS 1.2+ everywhere, HSTS, modern ciphers. Internal service-to-service traffic uses mTLS.
  • At rest. Database and object storage encrypted with managed keys (envelope encryption). Backups encrypted.
  • Field-level. The most sensitive PII (identity-document numbers, financial account identifiers, medical-record content) is encrypted at the field or blob level with keys separate from the database, so a database compromise does not expose plaintext.
  • Documents. Stored in encrypted object storage; access only via short-lived, audited, pre-signed URLs; never served from a public bucket.
  • Key management. Keys live in a managed KMS, are rotated on a schedule, and are access-controlled and audited. The application never handles raw key material.

5. Secret management

  • All secrets (provider keys, signing keys, database credentials) live in a managed secrets store, scoped per environment and per service, and are rotated.
  • No secrets in source, in the static bundle, or in client code. The static front-end can hold only public values (for example the API base URL via NEXT_PUBLIC_*). Anything secret is server-side.
  • Secret access is least-privilege and audited; CI/CD reads secrets at deploy time from the store, not from the repository.
  • Webhook signing secrets and HMAC keys are per-provider and rotated; old keys are honoured during a rotation window.

6. Audit logging

  • What is logged. Every clinical, financial, consent, visa, access-control and case-status action: document verification, escrow funding and release, milestone confirmation, refunds, visa submission and grant, consent grant and withdrawal, role and permission changes, and support access.
  • Shape. Append-only events with entity, entity id, action, actor id and role, before and after state, source IP, request id and timestamp (see the audit model).
  • Integrity. Logs are immutable and tamper-evident; retention matches the highest applicable regime.
  • Use. Audit logs back SLA measurement, dispute resolution, DSAR responses, and security investigation.

7. PII handling guidelines

  • Classify. Data is classified (public, internal, PII, sensitive PII including health and financial). Handling rules follow the class.
  • Minimise. Collect and transmit only what a step needs. Visa and consultation workflows request specific documents, not blanket records. Integrations receive the minimum fields.
  • Restrict. Access is role- and case-scoped; sensitive fields are gated within a role; support access is consent-gated and audited.
  • Encrypt. Sensitive PII is field- or blob-level encrypted; documents live in encrypted object storage.
  • Reside. Storage and processing honour the corridor dataRegime and any residency constraint in the Country Pack.
  • Retain and erase. Follow the retention schedule; honour DSAR access, correction and deletion; apply legal holds that override deletion.
  • Never exfiltrate. Sensitive data stays inside managed surfaces; it is never pasted into unmanaged tools or logged in plaintext.

8. Compliance requirements

The platform must satisfy multiple regimes at once: India DPDP, GDPR for EU-adjacent patients, HIPAA for US data and partners, and corridor-specific rules, plus the NMC anti-commission boundary and sanctions and AML obligations. The product-level detail is in Legal, Compliance and Policy. Engineering obligations:

  • Build the consent ledger and DSAR workflow as first-class services.
  • Implement per-corridor data residency driven by Country Packs.
  • Implement sanctions and AML screening on payments and enhanced-risk corridors, blocking escrow release on an open match.
  • Enforce breach detection and notification within the regulatory timelines.
  • Keep the facilitator-not-provider boundary in product copy and in data handling (no clinical decisioning in the platform).

9. Secure API design standards

  • Authenticate then authorise every request; deny by default; never trust the client for access decisions.
  • Validate all input against the schema at the boundary; reject unknown fields; bound sizes and lengths.
  • Idempotency on every create and money or booking operation.
  • No sensitive data in URLs (use the body or headers); tokens in the Authorization header only.
  • Rate limit per token and IP; stricter limits on auth and money endpoints; lockout and backoff on auth.
  • Stable, minimal error contract that never leaks internals; a requestId on every response.
  • Output encoding and content-type enforcement to prevent injection; parameterised queries only.
  • Least-privilege service identities; service-to-service auth with mTLS or signed tokens.
  • Versioned, backward-compatible changes; deprecations announced and dual-run.
  • Security headers on the web tier (CSP, HSTS, X-Content-Type-Options, Referrer-Policy) and a WAF at the edge.
  • Test the controls. Authorization, tenant isolation, idempotency and rate limiting are covered by automated tests; run a periodic security review (the repository provides a security-review workflow).