Data Contract Protocol

The Data Contract Protocol is a standardised interface that enables Shell platform services to manage user data across consumer applications. It provides a consistent way to describe, export, and delete user data — ensuring compliance with privacy regulations and app store requirements.

Why It Exists

App stores (Apple, Google) and privacy regulations (GDPR, CCPA) require that users can:

• Know what data an app stores about them
• Export their data in a portable format
• Delete their data on request

Every Shell app must implement these capabilities. The Data Contract Protocol standardises this so the platform can orchestrate data operations across all apps from a single control plane.

How It Works

Each consumer app exposes a Data Contract endpoint — a single URL that handles three operations:

POST /data-contract/describe   → What data do you store for this user?
POST /data-contract/export     → Give me this user's data
POST /data-contract/delete     → Delete this user's data

The platform authenticates requests using HMAC signatures, ensuring only authorised callers can trigger data operations.

Architecture

┌──────────────┐       HMAC-signed requests       ┌──────────────────┐
│   Platform    │ ──────────────────────────────▶  │  Consumer App    │
│  Control Plane│                                  │  (Data Contract) │
└──────────────┘  ◀──────────────────────────────  └──────────────────┘
                        JSON responses

1. The platform sends an HMAC-signed request to the app's Data Contract endpoint
2. The app verifies the signature and processes the request
3. The app returns structured JSON describing the result
4. For deletions, the app can respond asynchronously with a tracking ID

Quick Start

Install the SDK and wire up your handlers:

npm install @shellapps/data-contract

import { createDataContract } from '@shellapps/data-contract'
 
const contract = createDataContract({
  secret: process.env.DATA_CONTRACT_SECRET,
  describe: async (userId) => ({ /* field descriptors */ }),
  export: async (userId) => ({ /* user data */ }),
  delete: async (userId) => ({ status: 'completed' }),
})

See the Implementation Guide for the full setup.