Develop a cross-origin messaging contract schema validating payloads, auth signatures,…
- User
Develop a cross-origin messaging contract schema validating payloads, auth signatures, and retries.
Assistant
The user wants a "cross-origin messaging contract schema" for validating payloads, authentication signatures, and handling retries. This sounds like a request for a JSON Schema or similar structural definition for an API that allows secure communication between different origins (domains).
1. Deconstruct the Request:
- Cross-origin: Implies communication between different domains/services (e.g.,
app.example.comtalking toapi.example.org). This usually involves CORS,postMessage, or just standard HTTP REST APIs where the "contract" is crucial. - Messaging Contract Schema: This is the core output. It's a definition of what the messages look like.
- Validating:
- Payloads: The actual data being sent.
- Auth Signatures: Ensuring the sender is who they say they are (HMAC, JWT, etc.).
- Retries: Mechanisms to handle delivery failures or idempotency (e.g., idempotency keys, retry counts).
2. Determine the Approach: I need to define a standard envelope structure that wraps the actual business logic (payload). This envelope should contain the metadata required for security and reliability.
- Core Concept: The "Envelope" pattern.
metadata: Contains auth, tracing, retry info.payload: The actual business data (polymorphic or generic).signature: The cryptographic proof.
3. Detailed Design of the Schema Components:
-
Component 1: The Envelope (Root)
- Needs a version (for schema evolution).
- Needs an ID (unique message ID).
- Needs a timestamp (replay attack protection).
-
Component 2: Authentication (The "Who")
- Who sent it? (
sender_id,origin). - Proof? (
signature). - Algorithm? (
alglike HS256, RS256). - Decision: Use a simple HMAC or signature structure similar to AWS Signature v4 or a simplified JWT-like approach but for raw HTTP bodies/webhooks. Let's stick to a detached JWS (JSON Web Signature) style or a simple HMAC-SHA256 hash header style for clarity.
- Who sent it? (
-
Component 3: Retry/Reliability (The "How")
- Idempotency Key: Crucial for retries so the receiver doesn't process the same message twice.
- Retry Count: How many times has this been attempted?
- Correlation ID: To link requests/responses.
-
Component 4: The Payload (The "What")
- Needs to be flexible. I'll define it as a generic object but note that specific implementations should define strict schemas for specific
typefields.
- Needs to be flexible. I'll define it as a generic object but note that specific implementations should define strict schemas for specific
-
Component 5: Signature Validation Logic (The Logic)
- The schema defines the shape of the signature, but I need to explain how to validate it (e.g., canonicalize JSON -> hash -> sign).
4. Drafting the Schema (JSON Schema format):
-
Draft thought: Should I use OpenAPI or just JSON Schema? JSON Schema is more portable for the "contract" aspect regardless of transport. I'll provide a robust JSON Schema.
-
Structure:
{ "$schema": "...", "type": "object", "properties": { "meta": { ... }, "payload": { ... }, "signature": { ... } } } -
Refining
meta:messageId: UUID.timestamp: ISO8601.retryCount: Integer.idempotencyKey: String (usually UUID).target: Where is this going? (Optional but good for cross-origin).
-
Refining
auth:keyId: Which key to use?algorithm: e.g., "hmac-sha256".
5. Addressing "Cross-Origin" Specifics: Since the prompt mentions "cross-origin," it implies browser-to-server or server-to-server (webhooks). If it's browser-to-server, CORS is handled by headers, but the payload contract is what the user asked for. I should mention how
originfits into the signature payload to prevent replay attacks across domains.6. Implementing Retry Logic: The schema defines the fields (
retryCount,maxRetries), but the logic defines the behavior (e.g., exponential backoff). I should include a "Contract Rules" section to explain this.7. Putting it together into a solution:
- Part 1: The JSON Schema. The concrete artifact.
- Part 2: Security Validation Protocol. How to generate and verify the signature (Canonicalization is key here).
- Part 3: Retry Strategy. How to use the schema fields for idempotency.
8. Refinement & Self-Correction during drafting:
- Critique: Just giving the JSON schema isn't enough. The "contract" implies rules, not just structure.
- Correction: I will split the response into "The Schema" (JSON) and "The Protocol" (Implementation Guide).
9. Final Polish:
- Ensure field names are clear (
message_idvsid). - Include examples.
- Use a standard hashing approach (HMAC-SHA256 is a safe default example).
(Self-Correction on Signature Location): Should the signature be part of the JSON or a header?
- Header approach: Standard HTTP webhooks.
- Embedded approach: Good for
postMessageor raw WebSocket frames where headers don't exist. - Decision: I will design an "Enveloped Message" where the signature is embedded or linked, as it's most versatile for "messaging contracts" generally, but I'll note that for HTTP, headers are preferred. Actually, let's stick to a Structured Payload (like a Signed Request Object or a secured event envelope) because it's transport-agnostic (works for WebSockets, PostMessage, Queues, HTTP).
10. Output Generation Plan:
- Overview: Define the Envelope pattern.
- The Schema (JSON): The strict definition.
- Validation Rules: Logic for Auth and Retries.
- Usage Example: A sample JSON.
Let's write the schema.
meta:version,timestamp,id,correlationId.delivery:attempt(0, 1, 2),maxAttempts,idempotencyKey.auth:sender,keyId.payload:type,data(generic).signature: The calculated hash.
This looks solid. Proceed to generate response. This contract defines a Secure Messaging Envelope. It is designed to be transport-agnostic (works for HTTP Webhooks, WebSocket messages, or Window
postMessage) ensuring that payloads remain tamper-proof and delivery is reliable.1. The Schema (JSON Schema Draft 7)
This schema defines the structure of the message. It separates concerns into three distinct nodes:
payload: The actual business data.meta: Routing, retry logic, and idempotency keys.auth: Cryptographic proof of origin.
{ "$schema": "http://json-schema.org/draft-07/schema#", "$id": "https://example.com/schemas/secure-messaging-contract-v1.json", "title": "Cross-Origin Messaging Contract", "description": "A validated envelope for secure cross-origin communication with retry support.", "type": "object", "required": ["meta", "payload", "auth"], "properties": { "meta": { "type": "object", "description": "Metadata for routing, tracing, and retry logic.", "required": ["messageId", "timestamp", "correlationId", "retryState"], "properties": { "messageId": { "type": "string", "format": "uuid", "description": "Unique ID for this specific message transmission." }, "correlationId": { "type": "string", "format": "uuid", "description": "ID linking a chain of requests/responses." }, "idempotencyKey": { "type": "string", "description": "Unique key to ensure processing occurs only once, regardless of retry count." }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 UTC timestamp of message creation." }, "ttl": { "type": "integer", "description": "Time-to-live in seconds. Message is invalid after this time.", "default": 60 }, "retryState": { "type": "object", "required": ["attempt", "maxAttempts"], "properties": { "attempt": { "type": "integer", "minimum": 0 }, "maxAttempts": { "type": "integer", "default": 5 }, "nextDelay": { "type": "integer", "description": "Suggested wait time in ms for next retry based on backoff strategy." } } } } }, "payload": { "type": "object", "description": "The application-level data.", "required": ["type", "data"], "properties": { "type": { "type": "string", "description": "The event type or action (e.g., 'user.created', 'payment.processed')." }, "data": { "type": "object", "description": "The actual business payload.", "additionalProperties": true } } }, "auth": { "type": "object", "description": "Security credentials and signature.", "required": ["senderId", "algorithm", "signature", "payloadHash"], "properties": { "senderId": { "type": "string", "description": "Identifier for the sending origin (e.g., 'service-A', 'https://app.example.com')." }, "algorithm": { "type": "string", "enum": ["HS256", "RS256", "EdDSA"], "description": "The cryptographic algorithm used." }, "payloadHash": { "type": "string", "description": "SHA-256 hash of the canonicalized payload to prevent tampering." }, "signature": { "type": "string", "format": "binary", "description": "The signature signing the payload hash and meta headers." }, "nonce": { "type": "string", "description": "Random value to prevent replay attacks within the timestamp window." } } } } }
2. The Validation Protocol (The Logic)
The schema defines the shape, but the contract defines how to process it. Here is the validation algorithm the receiver must implement.
Phase 1: Structural & Basic Validation
- Schema Check: Validate incoming JSON against the schema above.
- Timestamp Check (
meta.timestamp): EnsureNow() - timestamp < ttl. Reject stale messages (e.g., older than 60s) to mitigate replay attacks.
Phase 2: Integrity Validation (Payload Hashing)
Before checking the cryptographic signature, ensure the payload data matches the hash provided in the auth section. This prevents collision attacks where different payloads generate the same signature.
- Canonicalize: Serialize
payload.datato a deterministic string (e.g., sort keys alphabetically, remove whitespace). - Hash: Generate a SHA-256 hash of this string.
- Compare: Verify
computed_hash === auth.payloadHash.
Phase 3: Origin & Auth Validation
This verifies who sent the message and proves they possess the secret key.
- Lookup Key: Use
auth.senderIdto fetch the sender's public key (for RS256/EdDSA) or shared secret (for HS256) from your trust store. - Construct Signing String: Create a string consisting of:
meta.messageId + "|" + meta.timestamp + "|" + auth.payloadHash - Verify: Use the
auth.algorithmand the lookup key to verifyauth.signatureagainst the Signing String.
Phase 4: Retry & Idempotency Logic
If phases 1-3 pass, handle the delivery guarantees.
- Check Idempotency Key (
meta.idempotencyKey):- Query your processed messages cache/database.
- If Key Exists: Return the cached response immediately. Do not process the business logic again. This is the "At Least Once" delivery handling.
- If Key Missing: Proceed to process.
- Process Business Logic: Execute the action defined in
payload.type. - Failure Handling:
- If processing fails, check
meta.retryState.attemptagainstmaxAttempts. - If
attempt < maxAttempts, instruct the sender (or your retry queue) to retry withattempt++.
- If processing fails, check
3. Implementation Example (TypeScript)
Here is how a receiver would implement this contract using a generic validation function.
import crypto from 'crypto'; // Types matching the schema interface SecureEnvelope { meta: { messageId: string; timestamp: string; idempotencyKey: string; retryState: { attempt: number; maxAttempts: number }; }; payload: { type: string; data: any; }; auth: { senderId: string; algorithm: 'HS256' | 'RS256'; signature: string; payloadHash: string; }; } // Simulated Keystore const keyStore: Record<string, string> = { 'service-a': 'shared-secret-key-for-hmac', }; export async function validateContract(envelope: SecureEnvelope): Promise<boolean> { // 1. Time Validation (Replay protection) const msgTime = new Date(envelope.meta.timestamp).getTime(); const now = Date.now(); const ttlMs = 60000; // 60 seconds if (Math.abs(now - msgTime) > ttlMs) { throw new Error('Message expired or clock skew detected'); } // 2. Payload Integrity (Hash validation) // Canonicalization: Simple JSON stringify with sorted keys logic omitted for brevity const canonicalData = JSON.stringify(envelope.payload.data); const hash = crypto.createHash('sha256').update(canonicalData).digest('hex'); if (hash !== envelope.auth.payloadHash) { throw new Error('Payload hash mismatch - Data tampered'); } // 3. Signature Validation const secret = keyStore[envelope.auth.senderId]; if (!secret) throw new Error('Unknown Sender'); // Construct the string that was signed const signingString = `${envelope.meta.messageId}|${envelope.meta.timestamp}|${hash}`; // Verify HMAC-SHA256 const expectedSig = crypto .createHmac('sha256', secret) .update(signingString) .digest('base64'); if (expectedSig !== envelope.auth.signature) { throw new Error('Invalid Signature'); } // 4. Idempotency Check (Pseudo-code) const isProcessed = await checkDatabaseForIdempotencyKey(envelope.meta.idempotencyKey); if (isProcessed) { console.log('Duplicate message detected via Idempotency Key. Skipping processing.'); return true; } return true; } // Helper to simulate DB check async function checkDatabaseForIdempotencyKey(key: string): Promise<boolean> { // implementation depends on your DB (Redis, SQL, etc.) return false; }4. Summary of Retry Behavior
This contract assumes the Idempotent Receiver pattern.
- Sender: Generates a unique
idempotencyKeyfor every logical operation. If the sender times out and retries, it sends the same key with the same payload but incrementsretryState.attempt. - Receiver: Stores the result of the first successful processing tagged to the
idempotencyKey. Subsequent retries with the same key simply return the stored result without side effects.
- Cross-origin: Implies communication between different domains/services (e.g.,