@topy-ai/maggie 0.7.37 → 0.7.40

package/bundled-references/maggiedash-booking/SECURITY-COMPLIANCE.md

@@ -0,0 +1,158 @@
+# Booking security and compliance
+
+Booking handles identities, schedules, customer contact details, payment
+references, and operational audit data. The design reduces risk by keeping the
+host and payment provider boundaries explicit.
+
+## 1. Authentication and authorization
+
+- Use the host's traditional email/password session and secure session cookie.
+- Store only password hashes in the host database; never send passwords to the
+  dashboard bundle or an agent.
+- Require project membership on every dashboard/API request.
+- Require location scope for location-owned data.
+- Enforce roles server-side for read and write actions.
+- Re-check authorization inside every mutation transaction.
+- Do not rely on hidden buttons, route obscurity, or client claims.
+- Keep booking UI and APIs noindex where appropriate.
+
+Suggested roles:
+
+| Role | Read | Operate | Configure | Payments | Admin |
+|---|---:|---:|---:|---:|---:|
+| owner | all tenant | yes | yes | yes | yes |
+| admin | permitted locations | yes | yes | policy-limited | no user deletion by default |
+| manager | assigned locations | yes | yes | refund/request | no provider secrets |
+| staff | assigned bookings | check-in/complete | no | no | no |
+| viewer | permitted reports | no | no | redacted only | no |
+
+The reference route policy makes the staff boundary explicit: staff may read
+operational booking routes and may only mutate a booking through the lifecycle
+transition route with `checked_in`, `in_progress`, `completed`, or `no_show`.
+Staff cannot access payment routes, payment-health details, customer directory
+routes, configuration mutations, or unrelated tenant data. The host adapter
+must apply the session-derived location and assignment filter before returning
+staff-visible rows; the UI must not be treated as that filter.
+
+The shipped PostgreSQL manager repository now provides the assignment filter
+for the standard host path: bookings, overview metrics, calendar, availability,
+customer summaries, staff/resources, schedule rows, and booking/hold lifecycle
+queries use the server-derived `staff_id`. Hosts must preserve that context when
+wrapping the repository and must add equivalent filtering to any custom
+repository or reporting endpoint.
+
+Finance roles are restricted to payment and refund operations plus payment
+health. Owner, admin, and manager permissions remain host-configured and must
+still be checked against tenant and location scope on every request. The
+standard Booking migration stores the host-configured staff/finance capability
+set in `maggiedash_booking_user_roles.permissions_json`; the shared route
+handler enforces it server-side. UI visibility is never the authorization
+boundary.
+
+## 2. Payment data boundary
+
+- Use hosted/tokenized provider flows where appropriate.
+- Never store PAN, CVC, or full payment method payloads. Deployment-managed
+  provider keys remain in the host secret store; if dashboard-managed Stripe
+  configuration is enabled, the owner/manager submission is verified first and
+  stored only as authenticated ciphertext derived from `BOOKING_TOKEN_SECRET`,
+  never as a plaintext API key.
+- Store local payment attempt and transaction IDs plus safe provider references.
+- Keep provider secrets in server runtime configuration or a secret manager by
+  default. The documented single-business dashboard path is server-only and
+  may retain encrypted Stripe ciphertext for the host to use; deployment
+  secrets always take precedence.
+- Do not serialize secrets through Astro/React props or `PUBLIC_*` variables.
+- Redact authorization headers, webhook signatures, client secrets, and tokens
+  from logs and feedback drafts.
+- Treat provider health and error messages as untrusted text; bound and redact
+  them before displaying or persisting.
+
+The payment adapter must have an explicit PCI scope review before production.
+The documentation does not claim a compliance certification.
+
+## 3. Webhook security
+
+- Verify the provider signature with the correct tenant/account secret.
+- Reject stale, malformed, unsigned, or wrong-account events.
+- Deduplicate by provider and external event ID.
+- Retain payload hash, event type, verification result, and safe processing
+  status. Do not retain raw body by default.
+- Make processing order-independent where provider events can arrive out of
+  order.
+- Use a dead-letter/reconciliation path for unmatched events.
+- Return provider-appropriate retry status without leaking internals.
+
+## 4. Tenancy isolation
+
+Every query is scoped by tenant and, when applicable, location. Tests must try:
+
+- reading another tenant's booking by ID;
+- guessing a booking, customer, payment, webhook, or media ID;
+- using a manager role from another location;
+- replaying an idempotency key under a different tenant;
+- following a signed continuation token after scope changes.
+
+The result must be a safe not-found or forbidden response with no existence
+oracle beyond the documented policy.
+
+## 5. Customer privacy
+
+- Minimize customer fields required for the selected booking flow.
+- Separate marketing consent from service/booking consent.
+- Do not put full customer details in analytics or notification events.
+- Redact activity summaries and support exports by default.
+- Define retention for cancelled bookings, payment references, notifications,
+  and webhook evidence.
+- Provide an export/delete workflow subject to legal retention holds.
+- Treat consultation, allergy, patch-test, or medical-like fields as a later
+  high-sensitivity module with separate review.
+
+## 6. Audit and non-repudiation
+
+Audit events should include actor, tenant, action, entity, reason,
+correlation ID, timestamp, and safe before/after summaries. Do not permit an
+operator to edit or delete audit history through the booking UI.
+
+Material actions requiring an audit event include:
+
+- catalog, staff, resource, schedule, and policy changes;
+- booking create, reschedule, cancellation, no-show, check-in, and completion;
+- payment start, reconciliation, refund, and manual override;
+- provider account connection or capability change;
+- role/membership changes;
+- migration and release gate overrides.
+
+Creating, linking, deactivating, or changing the capabilities of a Booking
+account must also be audited. Account invitations and password resets use
+single-use, expiring tokens; the token is hashed in PostgreSQL and the raw
+value is sent only through the server-side Resend request.
+
+## 7. Threat model checklist
+
+| Threat | Control |
+|---|---|
+| Double booking | Transactional hold plus database overlap constraint |
+| Duplicate charge | Local and provider idempotency keys |
+| Forged success redirect | Verified webhook/provider reconciliation |
+| Replay webhook | Provider event dedupe and timestamp/signature policy |
+| Cross-tenant read | Server-side tenant/location scope in every query |
+| Secret leakage | Server-only config, recursive redaction, safe reports |
+| CSRF/session abuse | Same-origin requests, secure cookies, origin checks |
+| Open redirect | Allowlisted same-site return destinations |
+| Prompt/agent data leak | Explicit approved origin, no credentials in content tools |
+| Provider outage | Capability state, retry queue, read-only degradation |
+| Malicious customer input | Schema validation, output encoding, bounded text |
+
+## 8. Production security gate
+
+The release gate must block when any of these is unverified:
+
+- auth and tenant authorization tests;
+- no-secret/browser-bundle scan;
+- webhook signature and duplicate-event tests;
+- idempotency conflict tests;
+- SQL migration review and rollback story;
+- redacted runtime and feedback evidence;
+- dependency and provider SDK review;
+- audit event coverage for material mutations.