---
title: "ADR-014: Packaging native artifacts"
manual: "nr-vault"
version: "1.0"
permalink: "https://docs.typo3.org/permalink/netresearch/nr-vault:adr-014-packaging-native@1.0"
source: "Developer/Adr/ADR-014-PackagingNativeArtifacts.rst"
rendered: "2026-09-18T07:37:50+00:00"
---

# ADR-014: Packaging native artifacts {#adr-014-packaging-native-artifacts}

**Table of contents**

-   [Status](https://docs.typo3.org/permalink/netresearch/nr-vault:status@1.0)
-   [Date](https://docs.typo3.org/permalink/netresearch/nr-vault:date@1.0)
-   [Context](https://docs.typo3.org/permalink/netresearch/nr-vault:context@1.0)
-   [Decision](https://docs.typo3.org/permalink/netresearch/nr-vault:decision@1.0)
-   [Consequences](https://docs.typo3.org/permalink/netresearch/nr-vault:consequences@1.0)
-   [Alternatives considered](https://docs.typo3.org/permalink/netresearch/nr-vault:alternatives-considered@1.0)
-   [Related decisions](https://docs.typo3.org/permalink/netresearch/nr-vault:related-decisions@1.0)

## Status {#status}

Accepted

## Date {#date}

2026-01-12

## Context {#context}

Shipping native binaries inside extension packages:

-   complicates security review and supply-chain trust,
-   complicates updates (CVE patching),
-   complicates platform support (x86_64, aarch64, glibc vs musl),
-   and often triggers "no executables in extensions" policies in
    security-conscious environments.

We still want Rust as an optional performance/security feature where it makes
sense.

## Decision {#decision}

-   The default nr-vault distribution remains **PHP-only**
-   Rust transport artifacts are distributed as **separate platform-specific
    artifacts**, e.g.:

    -   OS packages (deb/rpm)
    -   Container images / sidecar
    -   A dedicated "engine package" download with checksums/signing
-   "Bundled binary inside extension" is allowed only for controlled managed
    environments and is not the default path

## Consequences {#consequences}

### Positive {#positive}

-   Better adoption in security-conscious TYPO3 environments
-   Clear update and patching model for native components
-   Cleaner separation of responsibilities and reduced TER friction

### Negative {#negative}

-   Additional installation steps for Rust mode
-   Requires CI/CD pipeline for multi-arch artifacts and release management

## Alternatives considered {#alternatives-considered}

### Bundle libvault.so directly in the extension {#bundle-libvault-so-directly-in-the-extension}

Ship the native library inside the TYPO3 extension package.

**Rejected** as default; allowed only in managed/special cases.

## Related decisions {#related-decisions}

-   [ADR-013: Rust FFI preload-only mode](https://docs.typo3.org/permalink/netresearch/nr-vault:adr-013-rust-ffi-preload@1.0) \- FFI security configuration
-   [ADR-012: SecureHttpClient API and transports](https://docs.typo3.org/permalink/netresearch/nr-vault:adr-012-secure-http-transports@1.0) \- Transport abstraction that uses FFI