Developer Docs

Install PixelSeal and embed your first watermark in under a minute.

npm install @pixelseal/core

// Embed a watermark const result = await embed({ inputPath: 'photo.jpg', outputPath: 'photo-sealed.png', creatorId: 'alice', hmacSecret: 'my-secret-key', });

console.log(result.assetId); // unique asset fingerprint console.log(result.embedHash); // HMAC integrity hash

// Verify later const check = await verify({ imagePath: 'photo-sealed.png', hmacSecret: 'my-secret-key', });

console.log(check.found); // true console.log(check.hmacValid); // true console.log(check.creatorId); // 'alice' ```

The `embed()` function encodes a steganographic watermark into an image using DCT-domain embedding with Reed-Solomon error correction.

Parameters

Return Value

interface EmbedResult {
  width: number;
  height: number;
  blocksUsed: number;
  payloadBits: number;
  assetId: string;
  embedHash: string;
}

The `verify()` function extracts and validates an embedded watermark using a 5-phase geo-recovery pipeline:

• **Direct decode** — standard extraction at original resolution
• **Alignment search** — small offsets to recover from sub-pixel shifts
• **Crop recovery** — scanning for watermark origin in cropped images
• **Scaled-grid extraction** — testing common resize dimensions
• **Scale search** — brute-force scale factor sweep

Parameters

Return Value

interface VerifyResult {
  found: boolean;
  creatorId?: string;
  assetId?: string;
  timestamp?: string;
  hmacValid?: boolean;
  recoveredHash?: string;
  phase?: string;     // which recovery phase succeeded
  bestScale?: number; // scale factor if resized
  failureReason?: string;
}

The PixelSeal Registry provides a public lookup layer for sealed images. When an image is embedded, you can optionally register it so that anyone verifying the image can look up the creator and provenance.

Endpoints

Example: Register an Asset

curl -X POST https://api.pixelseal.io/v1/registry/assets \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "assetId": "abc123...",
    "creatorId": "alice",
    "embedHash": "def456...",
    "metadata": { "title": "Sunset at Malibu" }
  }'

PixelSeal uses a layered security model to protect watermark integrity:

HMAC Signing Every watermark includes an HMAC-SHA256 signature computed over the payload (creator ID + asset ID + timestamp). The HMAC secret never leaves the creator's environment. Verification re-computes the HMAC and compares — if the payload was tampered with, the HMAC will fail.

DCT-Domain Embedding Watermark bits are encoded in the frequency domain of each 8×8 block, making them invisible to the human eye and resistant to lossy compression (JPEG, WebP). Mid-frequency coefficients are modified by adding or subtracting a strength value.

Reed-Solomon ECC The payload is protected with Reed-Solomon error correction (GF(2^8)), allowing recovery of up to 25% symbol errors per codeword. This provides resilience against cropping, compression artifacts, and moderate geometric transforms.

Threat Model | Attack | Resistance | |--------|-----------| | JPEG compression (Q70+) | ✅ Survives | | PNG re-encoding | ✅ Survives | | Cropping (up to 30%) | ✅ Recoverable via geo-recovery | | Resize (common dims) | ✅ Recoverable via scale search | | Screenshot | ⚠️ Partial — depends on scale | | Intentional overwrite | ❌ Destroys watermark | | Pixel-level editing | ⚠️ ECC can recover minor edits |

PixelSeal supports HMAC key rotation for organizations that need to cycle signing keys over time.

How It Works 1. Generate a new HMAC secret 2. Start embedding with the new key 3. Keep old keys in your verify configuration 4. When verifying, try each key in order — the correct key will produce a valid HMAC

Multi-Key Verification

for (const key of keys) { const result = await verify({ imagePath: 'photo.png', hmacSecret: key, }); if (result.found && result.hmacValid) { console.log('Verified with key:', key); break; } } ```

Best Practices - Rotate keys quarterly or annually - Never delete old keys — you may need to verify historical images - Store keys in a secure vault (e.g., AWS Secrets Manager, HashiCorp Vault) - Document which key was active during which time period

PixelSeal uses Reed-Solomon error correction codes over GF(2^8) to protect the embedded payload from data loss caused by image transformations.

Why ECC? When an image is compressed, cropped, or resized, some DCT coefficients are altered. Without ECC, even a single flipped bit would corrupt the payload. Reed-Solomon codes can reconstruct the original data even when a significant portion of symbols are damaged.

Parameters - **Field**: GF(2^8) with primitive polynomial 0x11D - **Codeword length**: Up to 255 symbols - **Error correction**: Can correct up to `t` symbol errors where `2t` parity symbols are added - **Current config**: ~25% redundancy (corrects ~12.5% of total symbols)

How It Works 1. The payload (creator ID, asset ID, timestamp, HMAC) is serialized to bytes 2. Reed-Solomon encoding adds parity symbols 3. The encoded data is converted to bits and embedded in DCT coefficients 4. During verification, the bits are extracted and RS decoding corrects any errors 5. If too many errors exist, the decoder signals failure

Galois Field Arithmetic All operations (add, multiply, divide) happen in GF(2^8): - Addition = XOR - Multiplication uses log/antilog tables - No floating point — everything is exact integer math

PixelSeal v1.1 introduced a 5-phase geo-recovery pipeline to handle geometric transformations that shift the watermark grid.

The Problem DCT watermarking relies on an 8×8 block grid aligned to the image origin. Any operation that shifts pixels — cropping, padding, resizing — misaligns the grid and prevents direct extraction.

Phase 1: Direct Decode Standard extraction assuming the grid is aligned. Works for unmodified images and re-compressed images.

Phase 2: Alignment Search Tests small offsets (±7 pixels in each direction) to find the correct grid origin. Handles minor crops and padding.

Phase 3: Crop Recovery Systematically scans a wide range of x/y offsets to locate the watermark origin in a cropped image. Searches in blocks of 8 for efficiency.

Phase 4: Scaled-Grid Extraction Tests common resize dimensions (1920, 1080, 800, 640, etc.) and reconstructs the original scale factor, then extracts with grid correction.

Phase 5: Scale Search Brute-force sweep of scale factors from 0.3× to 3.0× in small increments. Last resort for unusual resize dimensions.

Performance | Transform | Recovery Rate | Phase Used | |-----------|--------------|------------| | Unmodified | 100% | Phase 1 | | JPEG Q70 | 100% | Phase 1 | | Crop 5% | 100% | Phase 3 | | Resize 1080p | ~83% | Phase 4-5 | | Crop + Resize | ~70% | Phase 3-5 |