Skip to content

feat(runtime-services): add native ephemeral MariaDB provider#2062

Merged
chubes4 merged 3 commits into
mainfrom
feat/2060-native-mariadb-provider
Jul 26, 2026
Merged

feat(runtime-services): add native ephemeral MariaDB provider#2062
chubes4 merged 3 commits into
mainfrom
feat/2060-native-mariadb-provider

Conversation

@chubes4

@chubes4 chubes4 commented Jul 25, 2026

Copy link
Copy Markdown
Collaborator

Summary

  • add a generic provider: native, engine: mariadb runtime-service provider backed by a fresh private daemon and filesystem
  • publish runtime-service:mysql:native:mariadb through the public runtime descriptor and contract manifest for Homeboy Extensions #2412/#2413 negotiation
  • finalize managed service evidence only after cleanup across the result, run registry, and artifact pointer

Closes #2060

Threat model and isolation proof

  • UID 0 is rejected before allocation; native execution requires a provably unprivileged POSIX identity
  • recipes can select only the native provider and MariaDB engine; host, port, credentials, socket, defaults/config, basedir, datadir, PID, log, and containment paths are not configurable
  • every service receives a mode-0700 mkdtemp root containing its private socket, PID file, log, temporary directory, and fixed ext4 datadir image
  • initialization, daemon, administrative clients, formatter, mount, and unmount commands use argument arrays through validated util-linux prlimit; database commands begin with --no-defaults
  • the datadir is a 256 MiB ext4 image with exactly 4,096 inodes, mounted through unprivileged fuse2fs; device, byte, and inode geometry are proven before initialization
  • hosts fail closed unless prlimit, truncate, mkfs.ext4, fuse2fs, fusermount3, and working unprivileged FUSE containment are available
  • administration uses only the provider-owned Unix socket; the generated least-privilege runtime@127.0.0.1 account uses loopback TCP
  • passwords travel only through SQL stdin and the connector-scoped secret environment; tests scan plans, evidence, generated PHP, artifact pointers, argv, and persisted files for leakage
  • cleanup retains direct process handles in an ownership registry until child exit events prove termination; Linux start-time identity is revalidated before every signal and PID files are never trusted
  • stop failure is terminal, preserves process ownership, and prevents path removal; retries never clear ownership unless stop and exit both succeed
  • each startup attempt truncates its private log before launch, and bind-collision retry classification requires the current owned process to have exited
  • partial concurrent provisioning always releases successful peers before propagating another peer's failure

Hard resource containment

RLIMIT_AS      2147483648 bytes
RLIMIT_CPU     300 seconds
RLIMIT_FSIZE   134217728 bytes (daemon); 268435456 bytes (fixed filesystem image)
RLIMIT_NOFILE  512
RLIMIT_NPROC   512
RLIMIT_CORE    0
RLIMIT_MEMLOCK 0
Datadir bytes  268435456
Datadir inodes 4096

MariaDB additionally uses fixed 32 MiB buffer-pool maximums, 10 connections, one thread-pool group, disabled file-per-table storage, a 96 MiB maximum shared InnoDB data file, a 32 MiB maximum temp file, and a 32 MiB redo log. Linux evidence records post-readiness RSS; the real integration requires observed RSS at or below 128 MiB despite the 2 GiB hard address-space ceiling.

Cleanup state machine

  1. Request socket-only SHUTDOWN through the validated limited client.
  2. Wait for the retained child exit event.
  3. Signal TERM, then KILL only after Linux process identity revalidation if graceful shutdown does not exit.
  4. Unmount the bounded filesystem, retrying only transient EBUSY results.
  5. Prove the FUSE process exited, revalidate root device/inode identity and symlink safety, remove the complete private root, and verify absence.
  6. Persist cleanup status and final managed-service evidence atomically; terminal output/result/registry/artifact evidence contains only released/completed or bounded teardown-failure states.

Tests

  • npm run build
  • npm run test:runtime-services
  • npm run test:runtime-services-lifecycle
  • npm run test:native-mariadb-runtime-service-integration (three consecutive real runs)
  • npm run test:runtime-contract-manifest
  • npm run test:provider-runtime-contracts
  • npm run test:redaction
  • npm run test:schema-parity
  • npm run test:production-boundary-enforcement
  • npm run test:release-package-coverage

Coverage includes root rejection, missing containment capabilities, exact hard-limit argv, hostile filesystem geometry, stale-log retry refusal, daemon crash, bind collision, stop failure, cancellation at preflight/initialization/readiness/administration/runtime-account phases, path/symlink attacks, direct process ownership, successful-peer cleanup after partial concurrency failure, advisory locks, concurrent sessions/providers, transactions, multisite-compatible schema operations, Playground mysqli execution, final lifecycle evidence, output bounds, and secret redaction.

The real integration creates only provider-owned temporary ext4 images, FUSE mounts, and MariaDB processes and recursively proves cleanup. It never reads or contacts a production daemon, socket, credentials, defaults, or data directory.

Integration contract

Homeboy Extensions #2412 emits the generic runtime-service declaration documented in docs/native-mariadb-runtime-service.md. #2413 negotiates the stable public capability runtime-service:mysql:native:mariadb; WP Codebox owns all identity, process, filesystem, secret, and cleanup details.

@chubes4

chubes4 commented Jul 26, 2026

Copy link
Copy Markdown
Collaborator Author

Second-pass hardening is pushed in 34109bb4 (fix(runtime-services): close native MariaDB isolation gaps).

Implemented:

  • host-aware capability reporting backed by a real bounded-filesystem mount/write/unmount/cleanup probe
  • all MariaDB writable state, HOME, TMPDIR, cwd, plugins, and secure-file paths inside the bounded image
  • schema, semantic, and runtime enforcement of at most two native services
  • fixed-directory trusted binary resolution with root ownership/mode validation and sanitized child PATH
  • detached process-group ownership for initialization, FUSE, and daemon processes, including descendant-exit proof
  • empty plugin directory, least-privilege runtime grants, and enabled-engine allowlisting
  • single-flight cleanup with retry-consistent evidence
  • hostile initializer descendant, engine denial, plugin/path, service-budget, readiness, and concurrent cleanup tests
  • loopback-sentinel integration attacks for FEDERATED, CONNECT, SPIDER, S3, and INSTALL SONAME

Verification:

  • npm run build
  • npm run test:runtime-services
  • npm run test:runtime-services-lifecycle
  • npm run test:runtime-contract-manifest
  • npm run test:runtime-contract-package-exports
  • npm run test:schema-parity
  • npm run test:redaction
  • npm run test:release-package-coverage
  • npm run test:native-mariadb-runtime-service-integration

All focused tests passed. Real integration was explicitly skipped by the readiness gate with trusted-containment-tools-unavailable; the runtime descriptor therefore declares package support but does not advertise the active native capability on this host.

@chubes4
chubes4 merged commit 062ff5c into main Jul 26, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

feat(runtime-services): provision native ephemeral MySQL-compatible processes

1 participant