Skip to main content

Connector Security and Access

Merchant connectors are a sensitive integration surface. If they are implemented casually, one store’s external credentials can become a path into another store’s data or into the wider platform.

eshopOS treats connectors as a separate security domain for that reason.

Store-Scoped Ownership​

Every connector record belongs to one store.

That means:

  • a Shopify install is created for one store_id
  • OAuth state is tied to that same store
  • import jobs are tied to that store
  • mappings created from imports are tied to that store

This is the first boundary that prevents cross-merchant leakage.

Why Connectors Are Not Developer Apps​

Developer apps and public OAuth in eshopOS are used when another application needs to call the eshopOS public API.

Connectors are different:

  • eshopOS is the OAuth client
  • the external platform is the OAuth server
  • the merchant is connecting an outside store into eshopOS

Because the direction of trust is reversed, connectors need their own storage and route model.

Token Handling​

Connector provider tokens should never be treated like casual application settings.

They should be:

  • stored on the backend only
  • encrypted at rest
  • isolated per store
  • rotated or replaced when the provider reconnects
  • removed or invalidated when the merchant disconnects

They should not:

  • be returned to browser UI
  • be logged in plain text
  • be shared across stores
  • be copied into generic configuration tables

OAuth State Handling​

The OAuth state value is one of the most important pieces of the connector flow.

eshopOS should:

  • generate a fresh state value for each connect attempt
  • persist it with provider and store context
  • expire it quickly
  • mark it consumed after one use
  • reject callback attempts with missing or invalid state

Without this, the connect flow becomes vulnerable to callback confusion and store mixups.

What the Merchant Should Be Allowed to Do​

The merchant-facing dashboard should allow:

  • starting a connect flow
  • seeing connection status
  • seeing the linked external shop
  • disconnecting
  • viewing import history

The merchant-facing dashboard should not expose:

  • raw external tokens
  • low-level provider secrets
  • full OAuth payloads
  • debug internals that only operators need

Auditability​

Every meaningful connector action should be auditable.

At minimum:

  • connect started
  • callback completed
  • connector connected
  • connector disconnected
  • import preview started
  • import run started
  • import run failed
  • import run completed

Audit data should include the actor, store, provider, and time.

Least-Privilege Scope Design​

Provider access scopes are part of the security model.

The goal is not to request everything that might be useful one day. The goal is to request the smallest set that supports the current import job.

That matters because:

  • merchants trust narrower access more easily
  • compromised credentials have less value
  • future platform reviews are easier
  • platform behavior is easier to explain

Future Hardening​

As connectors mature, stronger controls should be added:

  • provider token rotation support where the provider allows it
  • scoped background workers per connector job
  • security event surfacing for connector changes
  • webhook verification for continuous sync flows
  • operator alerts for repeated callback failures or token-exchange failures

Operator Responsibility​

The operator running eshopOS still needs to protect the platform-level connector secrets, including:

  • provider client secret
  • callback domain integrity
  • environment configuration
  • deployment safety

If those are weak, store isolation alone is not enough.