Crate stegoeggo

Expand description

Image protection library for embedding legal-notice and rights-reservation metadata, with optional steganographic markers for redundant evidence.

Embeds rights-reservation and AI-training restriction notices into images, with optional best-effort steganographic markers for redundant evidence. Metadata injection is the primary deterrence mechanism; steganographic payloads are a supplementary channel that may survive casual modification.

§Protection Levels

Disabled: No protection applied
Light: Metadata injection plus minimal seed stego (Q-table seed for JPEG, LSB redundancy=1 for PNG/WebP). Metadata is the primary evidence channel.
Standard: Steganography + metadata injection. Stego is a redundant best-effort marker; metadata remains the primary deterrence mechanism.

§Protection Layers

Each protection level applies one or more layers:

Steganography - Optional hidden LSB payload (PNG, lossless WebP) or DCT perturbation (JPEG). A redundant best-effort evidence channel. Lossy WebP is not supported.
Metadata Injection - Visible rights-reservation and AI-training restriction metadata (XMP, IPTC, EXIF). This is the primary deterrence mechanism.

§JPEG/WebP/PNG Format Notes

Steganographic robustness varies by format — these are format realities, not implementation limitations. JPEG’s lossy compression inherently limits steganographic payload survival. For JPEG, the library stores a seed in quantization tables when those tables are preserved and uses F5-style DCT coefficient embedding for baseline JPEGs. Pixel-based stego payloads may not survive JPEG re-compression. Metadata injection is unaffected by format choice and remains the primary evidence channel regardless. For maximum steganographic verifiability, use PNG output format.

Verification priority for JPEG: metadata seed extraction > DCT quantization table seed > DCT coefficient extraction > pixel-based extraction.

§JPEG-in/JPEG-out Fast Path

When using process_image_bytes with JPEG input and JPEG output, the library takes a byte-only fast path that operates directly on DCT coefficients, avoiding decode/encode cycles. This path applies DCT steganography (F5 embedding) and metadata injection. For progressive JPEGs, the progressive encoding is preserved.

§Security Considerations

The library supports two verification profiles:

Without a MAC key (legal-notice mode): Steganographic payload verification uses a non-cryptographic CRC32 checksum with ECC redundancy. An attacker can forge valid-looking payloads, but this is acceptable because visible metadata markers prove intent and rights reservation. No MAC key is required for the legal-notice use case.

With a MAC key (authenticated provenance mode): The library uses HMAC-SHA256 for cryptographic payload verification. This proves the hidden payload was generated by a party with the configured secret, adding authenticated provenance evidence. Use this when you need cryptographic integrity for the steganographic channel:

use stegoeggo::{ProtectionContext, ProtectionLevel};

let ctx = ProtectionContext::default()
    .with_mac_key(b"your-secret-key".to_vec());

The primary deterrence mechanism is visible metadata injection (XMP, IPTC, EXIF markers) — not the steganographic layer. Even if an attacker strips the stego payload, the visible metadata markers remain as evidence of protection and legal warnings.

§WAF-Optimized Usage

use stegoeggo::{process_image_bytes, ProtectionContext, ProtectionLevel, ImageOutputFormat};

let ctx = ProtectionContext::new(0.5, 42)
    .with_format(ImageOutputFormat::Png)
    .with_mac_key(b"shared-verification-key".to_vec())
    .with_stego_redundancy(2)      // Lower = faster
    .with_jpeg_quality(85)        // Lower = smaller files
    .with_progressive_jpeg(true); // Progressive rendering for web

let input_bytes = std::fs::read("image.png")?;
let (protected, warnings) =
    stegoeggo::process_image_bytes_with_warnings(&input_bytes, ProtectionLevel::Standard, &ctx)?;
// Reverse proxies should log or enforce warnings before serving.

Legal Metadata

Embed copyright and usage restrictions in images for IP protection.

use stegoeggo::{ProtectionContext, LegalMetadata, ProtectionLevel};

let ctx = ProtectionContext::default()
    .with_legal_metadata(
        LegalMetadata::new()
            .with_copyright_holder("Example Corp")
            .with_contact_email("legal@example.com")
            .with_usage_terms("All Rights Reserved. No AI training permitted.")
    );

§Feature Flags

Feature	Description
`async`	Enables Tokio-based async wrappers (`process_image_async`, etc.) for WAF/CDN integration
`signatures`	Enables Ed25519 signing via `ed25519-dalek` for provenance claims and detached manifests
`detached-manifest`	Enables signed sidecar manifest support
`iscc`	Enables ISCC content identifier computation (`compute_content_identifiers`, etc.)
`conformance`	Enables the conformance harness binary and manifest parsing (TOML)
`parallel`	Enables Rayon-based parallel batch processing (`process_images_parallel`, etc.)
`test-seeds`	Enables fallback seed guessing during verification (tries common test/dev seeds). Used by the CLI; not recommended for library consumers
`fuzz`	Enables bounded JPEG dimension inspection for fuzz harnesses. It does not expose parser or coefficient types

§Tiled Steganography

For crop-resistant protection, enable tiled mode. The full payload is embedded in each tile_size × tile_size tile independently, so any crop containing at least one intact tile is recoverable:

use stegoeggo::{ProtectionContext, ProtectionLevel};

let ctx = ProtectionContext::new(0.5, 42)
    .with_tile_size(64);          // 64×64 tiles
let protected = stegoeggo::process_image_bytes(&img_bytes, ProtectionLevel::Standard, &ctx)?;

§Async API

For Tokio-based services (WAFs, CDN edge workers), use the async variants:

use stegoeggo::{process_image_bytes_async, ProtectionContext, ProtectionLevel};

let ctx = ProtectionContext::new(0.5, 42);
let protected = process_image_bytes_async(img_bytes, ProtectionLevel::Standard, ctx).await?;

§Parallel Batch Processing

Process multiple images concurrently using Rayon:

use stegoeggo::{process_images_parallel, ProtectionContext, ProtectionLevel};

let images: Vec<image::DynamicImage> = vec![ /* ... */ ];
let ctx = ProtectionContext::default();
let results = process_images_parallel(&images, ProtectionLevel::Standard, &ctx)?;

§Warnings API

process_image_bytes_with_warnings returns both the protected bytes and any warnings about the protection process (e.g., progressive JPEG fallback, insufficient DCT capacity):

use stegoeggo::{process_image_bytes_with_warnings, ProtectionContext, ProtectionLevel};

let ctx = ProtectionContext::new(0.5, 42);
let (protected, warnings) =
    process_image_bytes_with_warnings(&img_bytes, ProtectionLevel::Standard, &ctx)?;

for w in &warnings {
    eprintln!("Warning: {w}");
}

Re-exports§

pub use error::Error;
pub use error::Result;
pub use resource_limits::ResourceLimits;
pub use resource_limits::ResourceUsage;
pub use types::AuthenticationMode;
pub use types::HiddenMarkerMode;
pub use types::ProcessingOptions;
pub use types::DmiValue;
pub use types::EvidenceChannel;
pub use types::EvidenceProfile;Deprecated
pub use types::EvidenceStrength;
pub use types::ExecutionReport;
pub use types::ImageOutputFormat;
pub use types::LegalMetadata;
pub use types::LocalizedText;
pub use types::MetadataUpdatePolicy;
pub use types::NoticeVerification;
pub use types::NoticeVerificationBuilder;
pub use types::ProtectionChannels;
pub use types::ProtectionConfig;
pub use types::ProtectionContext;
pub use types::ProtectionLevel;
pub use types::ProtectionPreset;
pub use types::ProtectionRequest;
pub use types::ProtectionWarning;
pub use types::ResolvedProtectionPlan;
pub use types::RightsNotice;
pub use types::RightsPolicy;
pub use types::RightsSignalKind;
pub use types::VerificationResult;
pub use types::VerificationStatus;
pub use types::WarningCategory;
pub use types::WarningSeverity;
pub use types::DEFAULT_OUTPUT_FORMAT;
pub use types::PLUS_DATA_MINING_PROPERTY;
pub use types::PLUS_NAMESPACE;
pub use traits::Protector;
pub use async_api::process_image_async;async
pub use async_api::process_image_bytes_async;async
pub use async_api::process_image_bytes_with_warnings_async;async
pub use async_api::verify_image_bytes_async;async
pub use async_api::process_images_bytes_parallel_async;async and parallel
pub use async_api::process_images_parallel_async;async and parallel

Modules§

async_apiasync: Async wrappers for WAF/CDN edge integration.
conformanceconformance: Machine-readable conformance reporting for independent interoperability testing.
detacheddetached-manifest: Detached signed manifest support for provenance evidence.
error: Error types for the stegoeggo library.
payload_v3: V3 payload wire format: header, parser, types, and errors. V3 payload wire format: header, parser, types, and errors.
provenance: Provenance claim model for rights/provenance assertions about images. Provenance claim model for rights/provenance assertions about images.
resource_limits: Resource limits for parser hardening against malformed or adversarial inputs.
signingsignatures: Ed25519 signing support for provenance claims.
stego: Generic carrier APIs for arbitrary payloads.
traits: Core traits for the protection system.
types: Core types: protection levels, configuration, legal metadata, and verification results.
verification: Structured verification report and builder for legal-notice and stego verification.

Structs§

ContentIdentifiersiscc: Content identifiers computed from an image’s perceptual and data characteristics.
EmbedOutcomeSummary: Summary of a steganographic embedding attempt.
PassthroughProtector: No-op protector for the Disabled protection level.
ProtectionPipeline: Main pipeline for applying protection to images.
RightsMetadataProtector: Metadata injection protector for the Light protection level.
SteganographyProtector: Steganographic protection: embeds hidden payloads in image pixels or DCT coefficients.
StegoPayload: Extracted steganographic payload containing protection metadata.

Enums§

EmbedPath: The embedding path used for steganographic payload insertion.
EmbedStatus: Status of a steganographic embedding attempt.

Functions§

compute_content_identifiersiscc: Compute content identifiers from a DynamicImage.
compute_content_identifiers_from_bytesiscc: Compute content identifiers from raw image bytes.
compute_content_identifiers_from_bytes_with_metadataiscc: Compute content identifiers from raw image bytes with legal metadata.
compute_content_identifiers_with_metadataiscc: Compute content identifiers from a DynamicImage with legal metadata.
compute_image_hash: Compute a SHA-256 hash of an image’s raw RGBA pixel data.
compute_isccDeprecatediscc: Compute content identifiers from a DynamicImage.
compute_iscc_from_bytesDeprecatediscc: Compute content identifiers from raw image bytes.
compute_iscc_from_bytes_with_metadataDeprecatediscc: Compute content identifiers from raw image bytes with legal metadata.
compute_iscc_with_metadataDeprecatediscc: Compute content identifiers from a DynamicImage with legal metadata.
detect_image_format: Detect the image format from magic bytes.
encode_image: Encode an image to bytes in the given format with default quality (90).
encode_image_with_options: Encode an image with format selection, progressive JPEG support, and quality control.
generate_random_seed: Generate a cryptographically secure random seed.
is_progressive_jpeg: Returns whether a JPEG header declares progressive encoding.
load_image_from_bytes: Load a DynamicImage from raw bytes.
parse_jpeg_for_fuzzfuzz: Perform bounded JPEG structural inspection for fuzzing.
process_image: Process an image with the specified protection level.
process_image_bytes: Process image bytes with the specified protection level.
process_image_bytes_with_info: Process image bytes with protection level and return warnings about degraded protection.
process_image_bytes_with_warnings: Process image bytes with protection level and return all protection warnings.
process_images_bytes_parallelparallel: Process multiple images in parallel (bytes variant).
process_images_parallelparallel: Process multiple images in parallel.
process_request_bytes: Process image bytes using a ProtectionRequest.
process_request_bytes_with_report: Process image bytes using a ProtectionRequest, returning a full execution report.
process_request_bytes_with_warnings: Process image bytes using a ProtectionRequest, returning warnings.
resolve_request: Resolve a ProtectionRequest into an immutable execution plan.
verify_image_bytes: Verify that image bytes contain a protection payload whose integrity can be proved.
verify_image_bytes_detailed: Verify protection with detailed results.
verify_image_bytes_detailed_with_limits: Verify protection with detailed results and custom resource limits.
verify_image_bytes_with_limits: Verify protection with custom resource limits.
verify_legal_notice: Verify legal-notice metadata and steganographic status in a protected image.
verify_legal_notice_with_limits: Verify legal-notice metadata with custom resource limits.

Type Aliases§

IsccDeprecatediscc: ISCC-like (International Standard Content Code) identifier.
MetadataTrapProtectorDeprecated

Crate stegoeggo

Crate stegoeggo Copy item path

§Protection Levels

§Protection Layers

§JPEG/WebP/PNG Format Notes

§JPEG-in/JPEG-out Fast Path

§Security Considerations

§WAF-Optimized Usage

§Feature Flags

§Tiled Steganography

§Async API

§Parallel Batch Processing

§Warnings API

Re-exports§

Modules§

Structs§

Enums§

Functions§

Type Aliases§

Crate stegoeggo