Security Architecture

This page describes the trust boundaries and security controls in place today, what's known to be missing (per the audit), and the hardening roadmap.

The full audit lives in AUDIT.md. This page summarises the architectural picture; the audit carries every individual finding with file:line citations.

Trust boundaries

┌─────────────────┐    HTTPS     ┌─────────────────┐    AWS RDS    ┌────────────┐
│ vetty / vetdoc. │─────────────▶│  Laravel API    │──────────────▶│  MySQL     │
│ admin web       │              │  (Sanctum)      │               │            │
└─────────────────┘              └─────────────────┘               └────────────┘
                                          │
                                          ├──signed POST──▶  Razorpay (payments)
                                          ├──HTTPS API──▶   Mailgun / SES (email)
                                          └──signed POST◀── Razorpay webhook

Every boundary either uses HTTPS + Bearer token, an HMAC-signed callback, or a signed URL. There are no unsigned cross-app trust paths.

Authentication

• Sanctum personal access tokens for the API. Issued at login (POST /auth/login), returned in the JSON body. Mobile apps store and attach as Authorization: Bearer ….
• Filament admin uses session-based auth on a separate system_admin guard.
• Owner self-serve registration at POST /auth/owner/register.
• Password reset via password_reset_tokens — token is sent in the email, the DB stores its SHA-256 hash. requestReset is rate-limited at throttle:6,1; reset at throttle:10,1.

Audit gaps

• P0 — password reset doesn't revoke existing Sanctum tokens. Add $user->tokens()->delete() in the reset path and a POST /auth/logout-all endpoint.
• P1 — /auth/login and /auth/verify-reset-token aren't rate-limited.
• P3 — TOTP 2FA, Google/Microsoft SSO, magic link, IP allowlist, login-history visible to user are all on the enhancement roadmap.

Authorization

Defense in depth. See Multi-tenancy for the layers.

• auth:sanctum validates the user.
• tenant.resolve resolves and (should) verify the active tenant.
• require.permission:<key> blocks at the route boundary.
• Form-request validators tenant-scope Rule::exists.
• Controller enforcePermission and policy classes handle row-level decisions.
• Auditable trait writes every change to audit_logs.

Audit gaps

• P1 — Several controllers accept *_id from the body and validate via exists without scoping to the URL tenant. Audit recommends an AssertsTenantScope trait.
• P1 — tenant.resolve should re-check membership.
• P1 — require.premium:<feature> falls back to user's current_tenant_id when route lacks an explicit {tenant}.

Audit log

audit_logs is append-only, polymorphic over the auditable model. Every clinical / billing / admin write writes a row. The RecordAuditContext middleware injects:

• Actor user id (or system-admin id).
• Tenant id (active tenant for the request).
• IP, user-agent, request id.

Custom events outside the Eloquent lifecycle (e.g. receipt.emailed, appointment.checked_in) are written via auditCustomEvent($action, $before, $after) on the Auditable trait.

Audit gaps

• P2 — The Auditable snapshot allow-list should be required (default-deny) with password, remember_token, secret columns in a system-wide deny-list.
• P2 — Audit-log search + CSV export.

Webhooks

Razorpay is the only inbound webhook today. The handler:

1. Verifies HMAC signature via RAZORPAY_WEBHOOK_SECRET.
2. Routes on event field.
3. Mutates the appropriate payments row.

Audit gaps

• P0 — verify should re-fetch the canonical payment amount from Razorpay before mutating local state.
• P0 — Webhook should also re-fetch instead of trusting payload.amount.
• P0 — The gateway silently rejects events when the secret is unset; fail loudly in production.

Public surfaces

Public, unauthenticated routes in increasing risk:

1. /system/health — pong only.
2. /auth/* — rate-limited where applicable.
3. /providers/* — marketplace; only is_public=true tenants leak through.
4. /p/{slug} — lost-pet collar tag; only public_profile_enabled=true pets.
5. /shares/{code}, /shares/redeem — share-code lookup (controlled by owner).
6. /webhooks/razorpay — signed.

Audit gaps

• P0 — /p/{slug} JSON endpoint surfaces owner's client.phone even when lost-mode is off, and isn't rate-limited. Easy enumeration target.
• P1 — /providers/{tenant} is enumerable on numeric ids. Add throttle:30,1.

Frontend secure storage

App	Today	Recommended
vetty	SharedPreferences (plain)	flutter_secure_storage
vetdoctor	SharedPreferences (plain)	flutter_secure_storage
admin web	localStorage (XSS-stealable)	httpOnly Secure cookie + CSRF token

All three are flagged P0 in the audit and form Wave 1 of the implementation plan.

Transport security

• HTTPS-only at the reverse proxy.
• Sanctum cookies use Secure and SameSite=Lax.
• No certificate pinning in the Flutter clients today (audit P0). Recommended: pin the production cert via a SecurityContext in the ApiClient.

Secrets management

• .env for local; AWS Secrets Manager (or equivalent) in production.
• service_settings.value carries per-tenant secrets (Mailgun key, SES creds, future SMS key) encrypted with the cast.
• The audit log redacts password and remember_token snapshots; the per-model allow-list controls what gets recorded.

Resource exposure (Resource classes)

The audit recommends formalising three privilege tiers for JsonResource classes:

• Public — narrow, marketing-safe (today's ProviderListingResource).
• Scoped — for tenant members.
• Internal — for system admins.

Specific fields the audit calls out for removal: tenant_id from AppointmentResource, internal disk names from attachment resources.

Hardening roadmap

The audit's Wave 1 (≈5 dev-days) is pure security hardening. Items in priority order:

1. Razorpay verify + webhook re-fetch.
2. Webhook secret hard-fail when unset.
3. /p/{slug} rate-limit + opt-in + no fallback to client.phone.
4. Hash caregiver invite_token on store.
5. Sanctum-token revocation on password reset + logout-all endpoint.
6. Frontend secure-storage pivot in vetty / vetdoctor / admin web.
7. Certificate pinning in both Flutter apps.

Wave 2 carries the IDOR + race-condition cluster.

See AUDIT.md §10 for the full plan.