# ZCAM SDK

## Architecture

### Overview

The ZCAM SDK allows an integrating app to:

1. Take a picture
2. Generate and sign a valid C2PA manifest over the photo (including a signature using the device key) including bindings to generate an SP1 proof
3. Generate a verifiable SP1 proof that the signature is valid, was signed using a key bound to the app, and corresponds to the photo, attaching that to a valid C2PA manifest

The core flow uses cryptographic keys stored on the device's Secure Enclave to sign and attest that a photo was taken using the device's camera and has not been tampered with.

### Cryptographic Keys

The ZCAM architecture generates and leverages two keys:

| Key             | Purpose                        | Apple Attested |
| --------------- | ------------------------------ | -------------- |
| **Device Key**  | Signs over a hash of the photo | Yes            |
| **Content Key** | Signs the C2PA manifest        | No             |

Both keys live in the Secure Enclave of the iPhone device. Importantly, the device key is specifically attested to have been generated on the Secure Enclave and is scoped to the specific app.

### Photo Lifecycle

A photo progresses through three states to become a verified zphoto:

| State                 | C2PA Assertion      | Description                                                                                                                                    |
| --------------------- | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| **Raw**               | None                | Original photo taken by phone, including metadata. No verifiable, attested traits.                                                             |
| **Provable**          | `succinct.bindings` | Embeds a C2PA manifest including required inputs for generating a zero knowledge proof. This includes a signature using an Apple attested key. |
| **Verified (zphoto)** | `succinct.proof`    | Embeds a C2PA manifest including a verifiable zero knowledge proof that the photo was signed using a valid Apple attested key.                 |

```
Raw Photo → [Capture] → Provable Photo → [Prove] → Verified zphoto
                         (bindings)                    (proof)
```

### Flow

#### 1. Initialization

The SDK first gets initialized. The main logic here is to generate or load the two necessary keys (device key and content key).

#### 2. Capture

The capture step allows a user to take a photo and output a *provable* photo.

When a user wants to take a zphoto, the SDK opens the camera screen. After the photo is taken, the SDK embeds a valid C2PA manifest by doing the following:

1. The photo is hashed, then signed using the device key. This outputs an Apple Attest assertion including a signature over the hash.
2. The C2PA manifest is initialized with a *capture* action including metadata: time of photo, OS, device model, software version, etc.
3. A `succinct.bindings` assertion is added to the manifest including data necessary to prove that the photo was signed using a valid Apple attested key.

![Capture flow diagram](/images/diagram_capture.png)

**Output:** A provable photo with a valid C2PA manifest containing metadata and an assertion that the photo was signed with an Apple attested key.

#### 3. Prove

The prove step takes the provable photo with C2PA manifest including a `succinct.bindings` assertion and generates a proof verifying its validity. This is done by using the SP1 Prover Network to prove the ZCAM program with the photo (and C2PA manifest) as input.

The SDK receives the proof from the network, then updates the photo and C2PA manifest:

* The `succinct.bindings` assertion is removed
* A `succinct.proof` assertion is added containing the verifiable proof

![Capture flow diagram](/images/diagram_prove.png)

**Output:** The final zphoto with a valid C2PA manifest including a verifiable proof.

#### 4. Verify

The SDK includes logic for parsing and verifying the proof from the C2PA manifest:

* Extract the manifest from the photo
* Verify the proof in the manifest
* Verify the photo hash matches the manifest


## FAQs

*TODO*


## Security

### Security Claims

A verified zphoto provides the following guarantees:

1. **Device Authenticity**: The photo was signed on a genuine Apple device with a Secure Enclave
2. **App Binding**: The signing key is bound to a specific application via Apple App Attest
3. **Content Integrity**: The photo has not been modified since the signature was created
4. **Proof Validity**: The above properties are verified in a zero-knowledge proof that chains to Apple's root certificate

### Trust Assumptions

The security of ZCAM relies on the following assumptions:

| Assumption                                | Rationale                                                     |
| ----------------------------------------- | ------------------------------------------------------------- |
| Secure Enclave keys cannot be exfiltrated | Hardware security guarantee from Apple                        |
| Apple App Attest is honest                | Apple signs attestations only for legitimate device/app pairs |
| SP1 proof system is sound                 | Groth16 proofs cannot be forged without the witness           |
| SDK code integrity                        | The SDK code on-device has not been tampered with             |

### Critical Assumption: Capture-to-Sign Integrity

:::warning
The SDK signs the photo immediately after capture, but there is no cryptographic binding
between the camera hardware and the signing operation. We assume no malicious code can
execute between the moment the photo is captured and when it is signed.
:::

This assumption holds if:

* The SDK code has not been tampered with
* The host application does not inject code into the capture flow
* The device is not compromised

This is an **operational security** assumption, not a cryptographic guarantee.

### Open Issues

#### App Trust Model

Currently, the SP1 program verifies that a photo was signed by *an* Apple Attested key,
but does not restrict *which* apps are trusted. A malicious app could:

1. Integrate the SDK
2. Feed AI-generated images to the signing flow
3. Generate valid proofs for inauthentic photos

**Mitigations under consideration:**

* Maintain a whitelist of trusted App IDs verified in the proof
* Output the App ID as a public value, allowing verifiers to check trust
* Require app attestation/audit before whitelist inclusion

#### Third-Party SDK Integration

As the SDK scales to third-party apps, we need mechanisms to ensure integrators
use the SDK as intended. Options include:

* Code signing / integrity checks on the SDK binary
* Runtime attestation of the SDK version
* Legal/contractual requirements for integrators

#### SDK Code Integrity

We need to guarantee the SDK code cannot be tampered with:

* **Build pipeline**: CI/CD must produce reproducible, auditable builds
* **On-device**: The SDK binary should be verified before execution
* **Updates**: SDK updates must be authenticated

This is not yet fully implemented.

### Inauthentic Photos

Even with cryptographic guarantees that a photo was captured by a genuine device running the SDK, attackers may attempt physical attacks:

* **Screen capture**: Photographing a screen displaying an AI-generated or manipulated image
* **Printed photo capture**: Photographing a printed image
* **Projector capture**: Photographing a projected image

These attacks bypass software-level protections because the camera genuinely captures "something" — just not an authentic scene.

Note that the taken photo is still "valid" in that it was taken using the camera app, properly signed etc. But the photo is still "inauthentic" in terms of what it is trying to portray.
This is a different, much harder problem to solve. In fact, a cryptographic solution is likely impossible. Instead, our strategy is to provide as much contextual data in the metadata for a user to be able to make an informed decision on the authenticity of the photo.

#### Detection Signals

The following metadata fields can help detect physical replay attacks:

| Field                                | What It Measures                        | Fraud Indicator                                                                            |
| ------------------------------------ | --------------------------------------- | ------------------------------------------------------------------------------------------ |
| **GPS / Location**                   | Location                                | Location inconsistent with claimed scene                                                   |
| **Timestamp**                        | Time                                    | Time inconsistent with lighting conditions                                                 |
| **Subject Distance**                 | Distance to focused subject             | Focus distance inconsistent with the subject of picture                                    |
| **Depth Map**                        | Per-pixel depth from dual cameras/LiDAR | Flat depth when the subject has more depth variance                                        |
| **White Balance**                    | Color temperature                       | Screen color temperature differs from natural light                                        |
| **Ambient Light**                    | Environmental light level               | Unusually uniform lighting could indicate screen glow                                      |
| **Focal Length ?**                   | Lens focal length used                  | Very short focal lengths (wide angle close-up) suggest photographing a nearby flat surface |
| \*\*Rolling Shutter Artifacts ? \*\* | Screen refresh banding                  | Horizontal bands indicate screen capture (refresh rate mismatch)                           |
| \*\*Moiré Patterns ? \*\*            | Interference patterns                   | Grid/wave patterns from screen pixels or print halftones                                   |
| \*\*Exposure Settings ? \*\*         | Shutter speed, ISO, aperture            | Unusual combinations for indoor screen photography                                         |
| \*\*Lens Distortion ? \*\*           | Optical distortion profile              | Comparing actual vs expected distortion for lens/distance                                  |

#### Implementation Status

:::note
These detection signals are not currently implemented in the SDK. They represent potential future enhancements to detect physical replay attacks.
:::


## ZK Proof Details

The SP1 program proves the following:

1. The photo bytes matches the expected bytes in the C2PA manifest
2. The Apple Attest attestation is valid
3. The assertion (i.e. signature of the photo hash using the attested key) is valid

The photo bytes are provided as input to the proof.

### Proof Logic

| Step | Operation                                    | Guarantees                                |
| ---- | -------------------------------------------- | ----------------------------------------- |
| 1    | Extract manifest from photo bytes            | —                                         |
| 2    | Extract bindings and data hash from manifest | —                                         |
| 3    | Compute photo hash                           | —                                         |
| 4    | Check data hash == photo hash                | Manifest corresponds to this photo        |
| 5    | Validate attestation                         | The attestation is valid and from Apple   |
| 6    | Validate assertion                           | Photo hash was signed by the attested key |

### Attestation Validation

Guarantees:

* The device key was generated in a genuine Apple Secure Enclave
* The key is bound to a specific app (via `app_id` / RP ID)
* The device is running a legitimate app (AAGUID = `appattest` or `appattestdevelop`)

Validates:

* Certificate chain verifies up to Apple Root CA
* Nonce matches the challenge
* Public key hash matches the key ID
* RP ID == SHA256(app\_id)
* AAGUID is a valid Apple attestation identifier

### Assertion Validation

Guarantees:

* The photo corresponding to this hash was signed using the ZCAM SDK

Validates:

* ECDSA signature over the photo hash using the public key from attestation

### Public Outputs

* Photo hash (SHA-256)
* Apple Root CA certificate

These committed values allow verifiers to confirm the proof corresponds to a specific photo and chains to Apple's actual root certificate.


## Capture SDK

The Capture SDK (`react-native-zcam1-capture`) takes photos and produces C2PA-signed assets bound to hardware-backed integrity signals.

### Installation

```bash
npm i react-native-zcam1-capture
cd ios && pod install
```

### Core Concepts

The Capture SDK:

* Renders a native iOS camera preview via `ZCamera`
* Generates App Attest assertions over photo hashes
* Embeds C2PA manifests with `succinct.bindings` assertion
* Returns signed photos ready for proof generation

### API Reference

#### `initCapture(settings)`

Initializes device keys and attestation. Call once on app startup.

```tsx
import { initCapture, CaptureInfo, Settings } from "react-native-zcam1-capture";

const settings: Settings = {
  appId: "TEAM_ID.com.example.app",
  production: false,
};

const captureInfo: CaptureInfo = await initCapture(settings);
```

**Parameters:**

* `settings.appId` - Your Team ID + Bundle ID
* `settings.production` - `false` for development, `true` for production

**Returns:** `CaptureInfo` containing:

* `appId` - The app identifier
* `deviceKeyId` - App Attest device key ID
* `contentPublicKey` - Secure Enclave content key
* `contentKeyId` - Derived content key identifier
* `attestation` - App Attest attestation blob

#### `ZCamera`

React component that renders the native camera preview.

```tsx
import { useRef } from "react";
import { ZCamera, CaptureInfo } from "react-native-zcam1-capture";

function CameraScreen({ captureInfo }: { captureInfo: CaptureInfo }) {
  const camera = useRef<ZCamera>(null);

  return (
    <ZCamera
      ref={camera}
      captureInfo={captureInfo}
      position="back"        // "front" | "back"
      isActive={true}        // Enable/disable camera
      style={{ flex: 1 }}
    />
  );
}
```

**Props:**

* `captureInfo` (required) - From `initCapture()`
* `position` - Camera to use: `"front"` or `"back"` (default: `"back"`)
* `isActive` - Whether camera is running (default: `true`)
* `style` - Style for the camera view

#### `ZCamera.takePhoto()`

Captures a photo and returns a signed `ZPhoto`.

```tsx
const photo = await camera.current?.takePhoto();

console.log(photo.originalPath); // Raw capture path
console.log(photo.path);         // C2PA-signed photo path
```

**Returns:** `ZPhoto` with:

* `originalPath` - Path to the raw captured image
* `path` - Path to the C2PA-signed image with `succinct.bindings`

### Complete Example

```tsx
import { useEffect, useRef, useState } from "react";
import { View, Button, Text, StyleSheet } from "react-native";
import { SafeAreaView } from "react-native-safe-area-context";
import { initCapture, ZCamera, CaptureInfo } from "react-native-zcam1-capture";
import { FileSystem, Dirs } from "react-native-file-access";

export function CaptureScreen() {
  const camera = useRef<ZCamera>(null);
  const [captureInfo, setCaptureInfo] = useState<CaptureInfo>();
  const [lastPhoto, setLastPhoto] = useState<string>();

  useEffect(() => {
    const settings = {
      appId: process.env.EXPO_PUBLIC_APP_ID!,
      production: false,
    };
    initCapture(settings).then(setCaptureInfo);
  }, []);

  const handleCapture = async () => {
    const photo = await camera.current?.takePhoto();
    if (!photo) return;

    // Save to app's document directory
    const destPath = `${Dirs.DocumentDir}/photos/${Date.now()}.jpg`;
    await FileSystem.mkdir(`${Dirs.DocumentDir}/photos`);
    await FileSystem.cp(photo.path, destPath);

    setLastPhoto(destPath);
  };

  if (!captureInfo) {
    return (
      <View style={styles.centered}>
        <Text>Initializing camera...</Text>
      </View>
    );
  }

  return (
    <SafeAreaView style={styles.container}>
      <ZCamera ref={camera} captureInfo={captureInfo} style={styles.camera} />
      <View style={styles.controls}>
        <Button title="Capture" onPress={handleCapture} />
        {lastPhoto && <Text>Saved: {lastPhoto}</Text>}
      </View>
    </SafeAreaView>
  );
}

const styles = StyleSheet.create({
  container: { flex: 1 },
  camera: { flex: 1 },
  controls: { padding: 16 },
  centered: { flex: 1, justifyContent: "center", alignItems: "center" },
});
```

### Notes

* `initCapture()` generates Secure Enclave keys on first call; subsequent calls load existing keys
* App Attest only works on physical devices; the SDK uses mock values in simulators
* The captured photo at `photo.path` contains a C2PA manifest with `succinct.bindings`—this is required for proof generation


## Picker SDK

The Picker SDK (`react-native-zcam1-picker`) provides an image picker component with built-in authenticity status badges.

### Installation

```bash
npm i react-native-zcam1-picker
cd ios && pod install
```

### Core Concepts

The Picker SDK:

* Displays a grid of images from a private folder or photo gallery
* Checks each image's C2PA authenticity status
* Supports custom badge rendering based on status
* Fires callbacks when images are selected

### API Reference

#### `ZImagePicker`

React component that renders a scrollable image grid.

```tsx
import { ZImagePicker } from "react-native-zcam1-picker";

<ZImagePicker
  source={{ path: "/path/to/folder" }}
  onSelect={(uri) => console.log("Selected:", uri)}
/>
```

**Props:**

* `source` - Image source (see below)
* `onSelect` - Callback when an image is tapped
* `renderBadge` - (Optional) Custom badge renderer

#### Source Types

**Private folder:**

```tsx
<ZImagePicker source={{ path: "/path/to/folder" }} />
```

**Photo gallery (with optional album filter):**

```tsx
<ZImagePicker source={{ album: "MyAlbum" }} />
```

#### `privateDirectory()`

Returns the app's private document directory path.

```tsx
import { privateDirectory } from "react-native-zcam1-picker";

const path = privateDirectory(); // e.g., /var/mobile/.../Documents
```

#### `AuthenticityStatus`

Enum indicating the C2PA status of an image.

```tsx
import { AuthenticityStatus } from "react-native-zcam1-picker";

AuthenticityStatus.Unknown        // Unable to determine
AuthenticityStatus.NoManifest     // No C2PA manifest
AuthenticityStatus.InvalidManifest // Manifest present but invalid
AuthenticityStatus.Bindings       // Has succinct.bindings (needs proof)
AuthenticityStatus.Proof          // Has succinct.proof (verified)
```

### Basic Usage

```tsx
import { ZImagePicker, privateDirectory } from "react-native-zcam1-picker";

export function PickerScreen() {
  const handleSelect = (uri: string) => {
    console.log("Selected:", uri);
  };

  return (
    <ZImagePicker
      source={{ path: `${privateDirectory()}/photos` }}
      onSelect={handleSelect}
    />
  );
}
```

### Rendering Badges

Use `renderBadge` to display authenticity indicators:

```tsx
import { Image, StyleSheet } from "react-native";
import { ZImagePicker, AuthenticityStatus, privateDirectory } from "react-native-zcam1-picker";

const styles = StyleSheet.create({
  badge: {
    position: "absolute",
    top: 6,
    right: 6,
    width: 18,
    height: 18,
  },
});

function renderBadge(status: AuthenticityStatus): React.ReactElement | null {
  switch (status) {
    case AuthenticityStatus.Bindings:
      return (
        <Image
          source={require("./assets/pending.png")}
          style={styles.badge}
          resizeMode="contain"
        />
      );
    case AuthenticityStatus.Proof:
      return (
        <Image
          source={require("./assets/verified.png")}
          style={styles.badge}
          resizeMode="contain"
        />
      );
    default:
      return null;
  }
}

export function PickerScreen() {
  return (
    <ZImagePicker
      source={{ path: privateDirectory() }}
      renderBadge={renderBadge}
      onSelect={(uri) => console.log(uri)}
    />
  );
}
```

### Complete Example with Proving

```tsx
import { useState } from "react";
import { View, Text, ActivityIndicator, StyleSheet } from "react-native";
import { ZImagePicker, AuthenticityStatus, privateDirectory } from "react-native-zcam1-picker";
import { useProver } from "react-native-zcam1-prove";
import { CameraRoll } from "@react-native-camera-roll/camera-roll";

export function PickAndProveScreen() {
  const { provingClient, isInitializing } = useProver();
  const [isProving, setIsProving] = useState(false);

  const handleSelect = async (uri: string) => {
    if (!provingClient || isProving) return;

    setIsProving(true);
    try {
      const provenPath = await provingClient.embedProof(uri);
      await CameraRoll.saveAsset(provenPath, { album: "ZCAM" });
      alert("Proof generated!");
    } catch (error: any) {
      alert(`Error: ${error.message}`);
    } finally {
      setIsProving(false);
    }
  };

  const renderBadge = (status: AuthenticityStatus) => {
    if (status === AuthenticityStatus.Bindings) {
      return <Text style={styles.badge}>📝</Text>;
    }
    if (status === AuthenticityStatus.Proof) {
      return <Text style={styles.badge}>✓</Text>;
    }
    return null;
  };

  if (isInitializing) {
    return <ActivityIndicator style={styles.centered} />;
  }

  return (
    <View style={styles.container}>
      {isProving && (
        <View style={styles.overlay}>
          <ActivityIndicator size="large" color="white" />
          <Text style={styles.overlayText}>Generating proof...</Text>
        </View>
      )}
      <ZImagePicker
        source={{ path: `${privateDirectory()}/captured` }}
        renderBadge={renderBadge}
        onSelect={handleSelect}
      />
    </View>
  );
}

const styles = StyleSheet.create({
  container: { flex: 1 },
  centered: { flex: 1, justifyContent: "center" },
  badge: { position: "absolute", top: 4, right: 4, fontSize: 14 },
  overlay: {
    ...StyleSheet.absoluteFillObject,
    backgroundColor: "rgba(0,0,0,0.7)",
    justifyContent: "center",
    alignItems: "center",
    zIndex: 1,
  },
  overlayText: { color: "white", marginTop: 8 },
});
```

### Permissions

#### iOS

Add to `Info.plist` when using photo gallery source:

```xml
<key>NSPhotoLibraryUsageDescription</key>
<string>This app needs access to your photos.</string>
```

#### Android

For Android 13+:

* `android.permission.READ_MEDIA_IMAGES`

For older versions:

* `android.permission.READ_EXTERNAL_STORAGE`

### Limitations

* Photo gallery source loads the first 20 photos (no pagination)
* Image list is loaded once on mount; source prop changes require remounting
* Single selection only
* Photos only (no videos)
* You must handle runtime permissions before rendering gallery source


## Prove SDK

The Prove SDK (`react-native-zcam1-prove`) generates zero-knowledge proofs for C2PA-signed images and embeds them back into the photo.

### Installation

```bash
npm i react-native-zcam1-prove
cd ios && pod install
```

### Core Concepts

The Prove SDK:

* Reads `succinct.bindings` from a captured photo's C2PA manifest
* Sends bindings to the prover backend for ZK proof generation
* Replaces `succinct.bindings` with `succinct.proof` in the manifest
* Returns a new photo file with the embedded proof

### API Reference

#### `ProverProvider`

React context provider that initializes the proving client. Wrap your app with this component.

```tsx
import { ProverProvider } from "react-native-zcam1-prove";

function App() {
  return (
    <ProverProvider settings={{ production: false }}>
      {/* Your app */}
    </ProverProvider>
  );
}
```

**Props:**

* `settings.production` - `false` for development, `true` for production
* `settings.privateKey` - (Optional) SP1 prover network private key

#### `useProver()`

Hook to access the proving client from within `ProverProvider`.

```tsx
import { useProver } from "react-native-zcam1-prove";

function ProveButton() {
  const { provingClient, isInitializing, error } = useProver();

  if (isInitializing) return <Text>Loading...</Text>;
  if (error) return <Text>Error: {error.message}</Text>;

  // Use provingClient...
}
```

**Returns:**

* `provingClient` - The `ProvingClient` instance (null while initializing)
* `isInitializing` - Whether the client is still being set up
* `error` - Any initialization error

#### `ProvingClient.embedProof(uri)`

Generates a proof for a photo and embeds it into the C2PA manifest.

```tsx
const { provingClient } = useProver();

const provenPath = await provingClient.embedProof(photoUri);
```

**Parameters:**

* `uri` - Path or URI to a photo with `succinct.bindings` assertion

**Returns:** Path to the new photo with `succinct.proof` embedded

**Throws:** Error if the input photo doesn't contain `succinct.bindings`

### Complete Example

```tsx
import { useState } from "react";
import { View, Button, Text, ActivityIndicator, StyleSheet } from "react-native";
import { useProver } from "react-native-zcam1-prove";
import { CameraRoll } from "@react-native-camera-roll/camera-roll";
import { launchImageLibrary } from "react-native-image-picker";

export function ProveScreen() {
  const { provingClient, isInitializing } = useProver();
  const [isProving, setIsProving] = useState(false);
  const [result, setResult] = useState<string>();

  const handlePickAndProve = async () => {
    // Pick a photo with succinct.bindings
    const response = await launchImageLibrary({
      mediaType: "photo",
      selectionLimit: 1,
    });

    const asset = response.assets?.[0];
    if (!asset?.uri || !provingClient) return;

    setIsProving(true);
    setResult(undefined);

    try {
      // Generate and embed the proof
      const provenPath = await provingClient.embedProof(asset.uri);

      // Save to camera roll
      await CameraRoll.saveAsset(provenPath, { album: "ZCAM" });

      setResult("Proof generated and saved!");
    } catch (error: any) {
      setResult(`Error: ${error.message}`);
    } finally {
      setIsProving(false);
    }
  };

  if (isInitializing) {
    return (
      <View style={styles.centered}>
        <ActivityIndicator size="large" />
        <Text>Initializing prover...</Text>
      </View>
    );
  }

  return (
    <View style={styles.container}>
      <Button
        title="Select Photo & Generate Proof"
        onPress={handlePickAndProve}
        disabled={isProving}
      />
      {isProving && (
        <View style={styles.status}>
          <ActivityIndicator />
          <Text>Generating proof... This may take a few seconds.</Text>
        </View>
      )}
      {result && <Text style={styles.result}>{result}</Text>}
    </View>
  );
}

const styles = StyleSheet.create({
  container: { flex: 1, padding: 16 },
  centered: { flex: 1, justifyContent: "center", alignItems: "center" },
  status: { marginTop: 16, alignItems: "center" },
  result: { marginTop: 16, textAlign: "center" },
});
```

### Using with Picker

Combine with `ZImagePicker` to show which photos need proving:

```tsx
import { ZImagePicker, AuthenticityStatus } from "react-native-zcam1-picker";
import { useProver } from "react-native-zcam1-prove";

function PickerScreen() {
  const { provingClient } = useProver();

  const handleSelect = async (uri: string) => {
    // Check if this photo needs a proof
    const status = await authenticityStatus(uri);

    if (status === AuthenticityStatus.Bindings && provingClient) {
      const provenPath = await provingClient.embedProof(uri);
      // Handle proven photo...
    }
  };

  return (
    <ZImagePicker
      source={{ path: privateDirectory() }}
      onSelect={handleSelect}
      renderBadge={(status) => {
        if (status === AuthenticityStatus.Bindings) return <Text>📝</Text>;
        if (status === AuthenticityStatus.Proof) return <Text>✓</Text>;
        return null;
      }}
    />
  );
}
```

### Notes

* Proof generation requires network access to the prover backend
* The input photo must have a `succinct.bindings` assertion (created by the Capture SDK)
* Proof generation typically takes a few seconds
* The original photo is not modified; a new file is created with the embedded proof


## Verify SDK

The Verify SDK (`react-native-zcam1-verify`) validates the authenticity of C2PA-signed photos with embedded proofs.

### Installation

```bash
npm i react-native-zcam1-verify
cd ios && pod install
```

### Core Concepts

The Verify SDK:

* Extracts C2PA manifests from photos
* Verifies the photo hash matches the manifest
* Validates the ZK proof against a pinned Apple Root CA
* Confirms the photo was taken on a genuine iOS device

### API Reference

#### `VerifiableFile`

Class for verifying photo authenticity.

```tsx
import { VerifiableFile } from "react-native-zcam1-verify";

const file = new VerifiableFile(photoUri);
```

**Constructor:**

* `uriOrPath` - File path or URI to the photo

#### `VerifiableFile.verifyHash()`

Checks that the photo's content hash matches the hash recorded in the C2PA manifest.

```tsx
const isHashValid: boolean = file.verifyHash();
```

**Returns:** `true` if the file contents haven't been tampered with

#### `VerifiableFile.verifyProof()`

Validates the embedded ZK proof against the photo hash and Apple Root CA.

```tsx
const isProofValid: boolean = file.verifyProof();
```

**Returns:** `true` if the proof is valid

### Complete Example

```tsx
import { useState } from "react";
import { View, Button, Text, StyleSheet } from "react-native";
import { launchImageLibrary } from "react-native-image-picker";
import { VerifiableFile } from "react-native-zcam1-verify";

type VerificationResult = {
  hashValid: boolean;
  proofValid: boolean;
  authentic: boolean;
};

export function VerifyScreen() {
  const [result, setResult] = useState<VerificationResult>();
  const [error, setError] = useState<string>();

  const handlePickAndVerify = async () => {
    setResult(undefined);
    setError(undefined);

    const response = await launchImageLibrary({
      mediaType: "photo",
      selectionLimit: 1,
    });

    const asset = response.assets?.[0];
    if (!asset?.uri) return;

    try {
      const file = new VerifiableFile(asset.uri);

      const hashValid = file.verifyHash();
      const proofValid = file.verifyProof();

      setResult({
        hashValid,
        proofValid,
        authentic: hashValid && proofValid,
      });
    } catch (err: any) {
      setError(err.message);
    }
  };

  return (
    <View style={styles.container}>
      <Button title="Select Photo to Verify" onPress={handlePickAndVerify} />

      {result && (
        <View style={styles.result}>
          <Text style={styles.title}>
            {result.authentic ? "✓ Authentic" : "✗ Not Authentic"}
          </Text>
          <Text>Hash Valid: {result.hashValid ? "Yes" : "No"}</Text>
          <Text>Proof Valid: {result.proofValid ? "Yes" : "No"}</Text>
        </View>
      )}

      {error && <Text style={styles.error}>Error: {error}</Text>}
    </View>
  );
}

const styles = StyleSheet.create({
  container: { flex: 1, padding: 16 },
  result: { marginTop: 24, padding: 16, backgroundColor: "#f0f0f0", borderRadius: 8 },
  title: { fontSize: 18, fontWeight: "bold", marginBottom: 8 },
  error: { marginTop: 16, color: "red" },
});
```

### Verification Helper

Create a reusable verification function:

```tsx
import { VerifiableFile } from "react-native-zcam1-verify";

export type VerificationStatus =
  | { status: "authentic" }
  | { status: "invalid_hash" }
  | { status: "invalid_proof" }
  | { status: "no_manifest" }
  | { status: "error"; message: string };

export function verifyPhoto(uri: string): VerificationStatus {
  try {
    const file = new VerifiableFile(uri);

    if (!file.verifyHash()) {
      return { status: "invalid_hash" };
    }

    if (!file.verifyProof()) {
      return { status: "invalid_proof" };
    }

    return { status: "authentic" };
  } catch (error: any) {
    if (error.message?.includes("no manifest")) {
      return { status: "no_manifest" };
    }
    return { status: "error", message: error.message };
  }
}
```

### What Verification Checks

| Check           | What It Validates                                       |
| --------------- | ------------------------------------------------------- |
| `verifyHash()`  | Photo bytes match the SHA-256 hash in the C2PA manifest |
| `verifyProof()` | ZK proof is valid and chains to the Apple Root CA       |

Both checks must pass for a photo to be considered authentic.

### Notes

* Verification is performed locally—no network required
* Only photos with `succinct.proof` assertion can be verified
* Photos with only `succinct.bindings` will fail `verifyProof()` (they haven't been proven yet)
* The Apple Root CA is pinned in the SDK; proofs must chain to this root


## Background

### C2PA

C2PA is an open source standard that allows parties to attach metadata that is *cryptographically bound* to a specified image. This is done using a *C2PA Manifest* which is tied to a specific image, including details and metadata about said image and also a cryptographic signature over these details.

The manifest can hold any information about the photo including metadata about what device it was taken on, size of the image etc. The key point is that it is signed using some key that attests to the accuracy of the associated information.

The manifest is then embedded directly into the photo file. The manner in which this is done depends. For example, it can be embedded into the metadata section of the JPEG file, or can be embedded as an invisible watermark encoding the manifest data.

ZCAM leverages the C2PA standard to embed a verifiable zero knowledge proof that the photo was taken on an iPhone and signed using a secure enclave private key that only the ZCAM SDK can use.

### Apple App Attest

ZCAM uses Apple's App Attest service to ensure that a ZPhoto was indeed *signed* by the ZCAM SDK.

The *intended* purpose of App Attest is to ensure requests coming from an app to a backend service is actually from the intended app. i.e. It guarantees that a backend service knows that it's only servicing requests from the associated mobile app.

At a high level, this is done by generating a new signing keypair on the device's secure enclave *that only the specific mobile app can access*. There is then a protocol for Apple to *attest* to the keypair as having been generated on said mobile app. This ensures any subsequent signatures using the keypair is guaranteed to be from the app.

![App Attest protocol diagram](/images/diagram_appattest.png)

Specifically, the App Attest protocol provides an attestation from Apple's backend server that is bound to some unique nonce and the public key of the secure enclave keypair. The app can then send this attestation as part of a request, such that the receiving backend service can verify the attestation.

Note, ZCAM leverages Apple App Attest, but uses it in a subtle but different way. There are two key differences:

1. The unique nonce used in the attestation is actually derived on the app itself, instead of receiving it from some backend service.
2. The attestation is verified in a zero knowledge proof instead of by a backend service.

### iOS Secure Enclave

TODO


## Introduction

Today, with the advent of AI generated images, liberal usage of editing software and increasing incentives to deceive and alter public perception, the importance of image integrity is at an all time high.

Succinct's ZCAM allows users to use their iPhones to create zphotos: These photos can be verified as authentic, unedited and indeed originating from their iPhone's camera. The ZCAM SDK allows any app to integrate this functionality, enabling them to leverage the ability take and verify zphotos in their app.

The core technology of zphotos and ZCAM is built on three components:

* **SP1 Zero Knowledge proofs**: Succinct's zero knowledge virtual machine can generate proofs that verify that certain code was ran as intended, and outputs succinct, small easily verifiable proofs
* **Apple App Attest**: The App Attest service allows an app to guarantee that a signing keypair is generated and stored on an Iphone's secure enclave, and belongs to a *specific* app on the iPhone.
* **C2PA**: C2PA is a standard that specifies how to embed verifiable metadata about an image within the actual image file. This includes details about the image, the history of the image etc.

The ZCAM sdk allows users to take a photo, sign the photo using an Apple attested key, and then embeds a zero knowledge proof verifying the signature along with the validity of the attested key to the image using C2PA.


## Installation

### Prerequisites

#### Rust Toolchain

The ZCAM SDK packages include Rust bindings built via UniFFI. You need Rust installed with iOS targets:

```bash
# Install Rust (if not already installed)
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Add iOS targets
rustup target add aarch64-apple-ios aarch64-apple-ios-sim
```

#### Xcode

Xcode is required for iOS development. Install it from the Mac App Store.

#### Development Environment

* Node.js 18+
* React Native 0.81+
* Expo SDK 54+ (if using Expo)

### Installing Packages

The ZCAM SDK is divided into standalone packages. Install only what you need:

```bash
# Full flow (capture, prove, verify)
npm i react-native-zcam1-capture react-native-zcam1-prove react-native-zcam1-verify

# Install native dependencies
cd ios && pod install
```

Individual packages:

| Package                      | Purpose                               |
| ---------------------------- | ------------------------------------- |
| `react-native-zcam1-capture` | Take photos with C2PA manifests       |
| `react-native-zcam1-prove`   | Generate ZK proofs for photos         |
| `react-native-zcam1-verify`  | Verify photo authenticity             |
| `react-native-zcam1-picker`  | Image picker with authenticity badges |

:::warning
The UniFFI bindings are built during `npm install`. This can take several minutes on first install.
:::

### iOS Configuration

#### Bundle Identifier

Configure your app's bundle identifier in your project. For Expo apps, set it in `app.json`:

```json
{
  "expo": {
    "ios": {
      "bundleIdentifier": "com.yourcompany.yourapp"
    }
  }
}
```

#### App ID for App Attest

You'll need your Apple Team ID combined with your bundle identifier. The format is:

```
<TEAM_ID>.<BUNDLE_IDENTIFIER>
```

For example: `NLS5R4YCGX.com.yourcompany.yourapp`

To find your Team ID:

1. Open Keychain Access on your Mac
2. Find a certificate named "Apple Development"
3. The Team ID is the "Organizational Unit" field

#### Required Permissions

Add these keys to your `Info.plist` (or `app.json` for Expo):

```json
{
  "expo": {
    "ios": {
      "infoPlist": {
        "NSCameraUsageDescription": "This app uses your camera to capture photos.",
        "NSPhotoLibraryUsageDescription": "This app needs access to save photos."
      }
    }
  }
}
```

### Environment Variables

Create a `.env` file with your configuration:

```bash
EXPO_PUBLIC_APP_ID=<TEAM_ID>.<BUNDLE_IDENTIFIER>
EXPO_PUBLIC_BACKEND_URL=https://your-backend-url.com
```

### Running on Device

App Attest requires a physical iOS device—it does not work in the simulator (the SDK falls back to mock mode for development).

```bash
# Expo
npx expo prebuild
npx expo run:ios --device

# React Native CLI
npx react-native run-ios --device
```

On first run, you may need to trust the developer certificate on your device:
**Settings → General → Device Management → Trust**


## Quickstart

This guide demonstrates a complete flow: capturing a photo, generating a proof, and verifying it.

### Setup

Wrap your app with the `ProverProvider` to enable proof generation:

```tsx
// App.tsx or _layout.tsx
import { ProverProvider } from "react-native-zcam1-prove";

export default function App() {
  return (
    <ProverProvider settings={{ production: false }}>
      {/* Your app */}
    </ProverProvider>
  );
}
```

### Step 1: Capture a Photo

Initialize the capture SDK and use the `ZCamera` component:

```tsx
import { useEffect, useRef, useState } from "react";
import { Button, View } from "react-native";
import { initCapture, ZCamera, CaptureInfo } from "react-native-zcam1-capture";

export function CaptureScreen() {
  const camera = useRef<ZCamera>(null);
  const [captureInfo, setCaptureInfo] = useState<CaptureInfo>();

  const settings = {
    appId: process.env.EXPO_PUBLIC_APP_ID!,
    production: false,
  };

  useEffect(() => {
    initCapture(settings).then(setCaptureInfo);
  }, []);

  const handleCapture = async () => {
    const photo = await camera.current?.takePhoto();
    if (photo) {
      console.log("Captured:", photo.path);
      // photo.path contains a C2PA-signed image with succinct.bindings
    }
  };

  if (!captureInfo) return null;

  return (
    <View style={{ flex: 1 }}>
      <ZCamera ref={camera} captureInfo={captureInfo} style={{ flex: 1 }} />
      <Button title="Capture" onPress={handleCapture} />
    </View>
  );
}
```

### Step 2: Generate a Proof

Use the `useProver` hook to access the proving client:

```tsx
import { useProver } from "react-native-zcam1-prove";
import { CameraRoll } from "@react-native-camera-roll/camera-roll";

export function ProvePhoto({ photoUri }: { photoUri: string }) {
  const { provingClient, isInitializing } = useProver();

  const handleProve = async () => {
    if (!provingClient) return;

    // Generate proof and embed it in the photo
    const provenPath = await provingClient.embedProof(photoUri);

    // Save to camera roll
    await CameraRoll.saveAsset(provenPath, { album: "ZCAM" });
    console.log("Proof generated:", provenPath);
  };

  if (isInitializing) return <Text>Initializing prover...</Text>;

  return <Button title="Generate Proof" onPress={handleProve} />;
}
```

### Step 3: Verify a Photo

Use the `VerifiableFile` class to verify authenticity:

```tsx
import { VerifiableFile } from "react-native-zcam1-verify";

export function VerifyPhoto({ photoUri }: { photoUri: string }) {
  const handleVerify = () => {
    const file = new VerifiableFile(photoUri);

    const hashValid = file.verifyHash();
    const proofValid = file.verifyProof();

    if (hashValid && proofValid) {
      console.log("Photo is authentic!");
    } else {
      console.log("Verification failed");
    }
  };

  return <Button title="Verify" onPress={handleVerify} />;
}
```

### Complete Example

Here's a minimal app combining all three steps:

```tsx
import { useState, useRef, useEffect } from "react";
import { View, Button, Text } from "react-native";
import { ProverProvider, useProver } from "react-native-zcam1-prove";
import { initCapture, ZCamera, CaptureInfo } from "react-native-zcam1-capture";
import { VerifiableFile } from "react-native-zcam1-verify";

function MainScreen() {
  const camera = useRef<ZCamera>(null);
  const [captureInfo, setCaptureInfo] = useState<CaptureInfo>();
  const [photoPath, setPhotoPath] = useState<string>();
  const [provenPath, setProvenPath] = useState<string>();
  const { provingClient } = useProver();

  const settings = {
    appId: process.env.EXPO_PUBLIC_APP_ID!,
    production: false,
  };

  useEffect(() => {
    initCapture(settings).then(setCaptureInfo);
  }, []);

  const capture = async () => {
    const photo = await camera.current?.takePhoto();
    if (photo) setPhotoPath(photo.path);
  };

  const prove = async () => {
    if (!provingClient || !photoPath) return;
    const path = await provingClient.embedProof(photoPath);
    setProvenPath(path);
  };

  const verify = () => {
    if (!provenPath) return;
    const file = new VerifiableFile(provenPath);
    const isValid = file.verifyHash() && file.verifyProof();
    alert(isValid ? "Authentic!" : "Invalid");
  };

  if (!captureInfo) return <Text>Initializing...</Text>;

  return (
    <View style={{ flex: 1 }}>
      <ZCamera ref={camera} captureInfo={captureInfo} style={{ flex: 1 }} />
      <Button title="1. Capture" onPress={capture} />
      <Button title="2. Prove" onPress={prove} disabled={!photoPath} />
      <Button title="3. Verify" onPress={verify} disabled={!provenPath} />
    </View>
  );
}

export default function App() {
  return (
    <ProverProvider settings={{ production: false }}>
      <MainScreen />
    </ProverProvider>
  );
}
```

### What Happens Under the Hood

1. **Capture**: Takes a photo, generates an App Attest assertion over the photo hash, and embeds a C2PA manifest with `succinct.bindings`.

2. **Prove**: Sends the bindings to the prover backend, which generates an SP1 zero-knowledge proof. The proof is embedded as `succinct.proof` in the C2PA manifest.

3. **Verify**: Recomputes the photo hash, verifies it matches the manifest, and validates the ZK proof against the pinned Apple Root CA.