Offline Verification

Offline verification allows checking whether an asset has been revoked without making an API call. This is critical for defence, field inspection, and air-gapped environments.

How It Works

1. Sync — Download a compact Cuckoo filter from the API containing all revoked serials
2. Verify locally — Check any serial against the filter in microseconds
3. Re-sync periodically — Update the filter to catch new revocations

The filter is a binary blob: 19-byte header + bucket data + 64-byte Ed25519 signature. The signature ensures the filter hasn't been tampered with.

Usage

TypeScript

import { verifyOffline, parseFilterHeader, StaleFilterError } from 'optropic';

// 1. Download the filter (do this periodically)
const response = await client.sync.downloadFilter();
const filterBuffer = response.data; // ArrayBuffer

// 2. Parse the header to check freshness
const header = parseFilterHeader(filterBuffer);
console.log(`Filter version: ${header.version}`);
console.log(`Generated: ${header.timestamp}`);
console.log(`Entries: ${header.entryCount}`);

// 3. Verify a serial offline
const result = verifyOffline(filterBuffer, 'SER-abc123', {
  maxAgeMs: 24 * 60 * 60 * 1000, // reject filters older than 24h
});

if (result.valid) {
  console.log('✓ Not revoked (as of last sync)');
} else {
  console.log(`✗ ${result.reason}`); // 'revoked' or 'stale_filter'
}

Python

from optropic import Optropic

client = Optropic(api_key="optr_live_...")

# 1. Download the filter
filter_data = client.sync.download_filter()

# 2. Verify offline
result = client.sync.verify_offline(filter_data, "SER-abc123")

if result["valid"]:
    print("✓ Not revoked (as of last sync)")
else:
    print(f"✗ {result['reason']}")

Filter Freshness

The Cuckoo filter includes a timestamp. You can configure a maximum age to reject stale filters:

try {
  const result = verifyOffline(filterBuffer, serial, {
    maxAgeMs: 3600_000, // 1 hour
  });
} catch (err) {
  if (err instanceof StaleFilterError) {
    // Filter is too old — re-sync
    const fresh = await client.sync.downloadFilter();
  }
}

Defence Use Case

For air-gapped environments, the filter can be transferred via USB or secure file transfer. The Ed25519 signature ensures integrity even when transferred over untrusted channels.

Limitations

Offline verification can only detect revoked assets. It cannot confirm an asset exists or verify its full provenance chain. For full verification, use the online client.assets.verify() method.