secure_db_fields 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 31ac55f3c53d7f1c6755f96f294cceacbc6f972891b46e809c1e4cc8222f5615
+  data.tar.gz: 2e918c0bbdffc6d95a60c6eb39e7c8f2a3345939e71c2d6d85c9745139cccb92
+SHA512:
+  metadata.gz: a872b172252d8df672af874f3dbacad680951fe6a178f428e4e7cad399a2d8b31d8bb62c9d5138ea354b26841b2e98b8c2e6a2c43fd37685d2bb4ee24b808727
+  data.tar.gz: efcdc09a8877b2a790b991a6f55bd399df7c29babc811ff1d10da8b5f0e2eaa584cd85dc3056798e68c69cd84852253f0c8dbff53647ba7e32a79f3e4b6191cf

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Roman Khaidarov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,98 @@
+# secure_db_fields
+
+`secure_db_fields` is a narrow field-level encryption layer for Ruby/Rails + MySQL 5.7.
+
+Compatibility target: Ruby >= 2.7.1 and MySQL 5.7. The gem intentionally avoids Ruby 3-only language/API features and the UDF avoids MySQL 8-only features such as functional indexes.
+It follows the locked design from `docs/final_decision.md`:
+
+- AES-256-GCM randomized envelope for confidential values.
+- HMAC-SHA256 blind indexes for exact indexed search.
+- Physical `*_bidx` columns, not generated columns.
+- MySQL UDFs for admin views/search helpers in DBeaver/DataGrip.
+- Keys outside the database and never passed as SQL arguments.
+- No `pq_crypto`, no OPE/FPE/range-preserving encryption, no transparent arbitrary `LIKE`.
+
+## Threat model
+
+Protected: raw table / SQL dump / physical column data leaked without key files.
+
+Not protected: DB host compromise, key-file compromise, or authorized admin access to decrypt UDF/views.
+
+## Ruby quick start
+
+```ruby
+require "secure_db_fields"
+
+keyring = SecureDBFields::Keyring.new("/etc/secure_db_fields/keys.env")
+uid = SecureRandom.random_bytes(16)
+phone = "+77771234567"
+
+aad = SecureDBFields::Crypto.aad("clients", "phone", uid)
+enc = SecureDBFields::Crypto.encrypt(phone, key: keyring.encryption_key(1), aad: aad, key_id: 1)
+bidx = SecureDBFields::Crypto.phone_blind_index(phone, key: keyring.blind_index_key("PHONE"))
+
+SecureDBFields::Crypto.decrypt(enc, key: keyring.encryption_key(1), aad: aad)
+# => "+77771234567"
+```
+
+## MySQL exact search template
+
+```sql
+SELECT
+  id,
+  secure_db_fields_decrypt_field(phone_enc, 'clients', 'phone', secure_row_uid) AS phone,
+  created_at
+FROM clients
+WHERE phone_bidx = secure_phone_bidx('+77771234567');
+```
+
+Do not search by plaintext through the decrypt view:
+
+```sql
+-- forbidden on large tables: decrypt-scan
+SELECT * FROM admin_clients_readable WHERE phone = '+77771234567';
+```
+
+## Prefix search
+
+Prefix search is not generic SQL `LIKE`. It is a named search mode with a physical column:
+
+```sql
+phone_bidx_p7 BINARY(32), INDEX idx_clients_phone_bidx_p7(phone_bidx_p7)
+```
+
+Only add prefix columns confirmed by query inventory. `last4`/suffix is intentionally not part of
+the default schema because it has very low cardinality and high leakage.
+
+## MySQL 5.7 DBA handoff bundle
+
+The application developer can build a self-contained database-host archive and pass it to the DBA:
+
+```bash
+bundle exec secure_db_fields db package mysql --output secure_db_fields-mysql.tar.gz --force
+```
+
+On the MySQL 5.7 server the DBA extracts the archive and runs:
+
+```bash
+make verify
+make doctor
+sudo make install
+make enable
+make status
+```
+
+Keys are intentionally not included in the archive. Provision `/etc/secure_db_fields/keys.env` on the DB host before using decrypt/search UDFs.
+
+Readable view SQL can be generated from the application side as well:
+
+```bash
+bundle exec secure_db_fields db view mysql \
+  --table app.clients \
+  --field phone:phone_enc \
+  --uid-column secure_row_uid \
+  --view admin.clients_readable \
+  --columns id,created_at \
+  --output clients_readable.sql
+```
+

data/Rakefile

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require "rake/testtask"
+require "rake/extensiontask"
+
+Rake::ExtensionTask.new("secure_db_fields", Gem::Specification.load("secure_db_fields.gemspec")) do |ext|
+  ext.lib_dir = "lib/secure_db_fields"
+end
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.pattern = "test/**/*_test.rb"
+end
+
+task default: %i[compile test]

data/db_deployment/mysql/Makefile

@@ -0,0 +1,62 @@
+SHELL := /bin/bash
+
+CC ?= cc
+CFLAGS ?= -O2 -fPIC -Wall -Wextra -Wformat -Wformat-security -fstack-protector-strong -D_FORTIFY_SOURCE=2 -std=c99
+LDFLAGS ?= -shared
+LIBS ?= -lcrypto
+MYSQL_CFLAGS ?= $(shell mysql_config --cflags 2>/dev/null)
+UDF_SO = secure_db_fields_mysql.so
+SRC = src/secure_db_fields_mysql.c src/secure_db_fields_core.c
+
+MYSQL ?= mysql
+MYSQL_DEFAULTS_FILE ?=
+MYSQL_SOCKET ?=
+CONFIRM ?=
+
+.PHONY: help all abi57 verify doctor install enable disable status uninstall clean
+
+help:
+	@printf '%s\n' \
+	  'SecureDBFields MySQL 5.7 deployment bundle' \
+	  '' \
+	  '  make verify' \
+	  '  make doctor [MYSQL_DEFAULTS_FILE=/etc/mysql/admin.cnf] [MYSQL_SOCKET=/run/mysqld/mysqld.sock]' \
+	  '  sudo make install [MYSQL_DEFAULTS_FILE=/etc/mysql/admin.cnf] [MYSQL_SOCKET=/run/mysqld/mysqld.sock]' \
+	  '  make enable [MYSQL_DEFAULTS_FILE=/etc/mysql/admin.cnf] [MYSQL_SOCKET=/run/mysqld/mysqld.sock]' \
+	  '  make status [MYSQL_DEFAULTS_FILE=/etc/mysql/admin.cnf] [MYSQL_SOCKET=/run/mysqld/mysqld.sock]' \
+	  '  make disable CONFIRM=DISABLE_SECURE_DB_FIELDS [MYSQL_DEFAULTS_FILE=/etc/mysql/admin.cnf] [MYSQL_SOCKET=/run/mysqld/mysqld.sock]' \
+	  '  sudo make uninstall CONFIRM=REMOVE_SECURE_DB_FIELDS [MYSQL_DEFAULTS_FILE=/etc/mysql/admin.cnf] [MYSQL_SOCKET=/run/mysqld/mysqld.sock]'
+
+all: abi57
+
+$(UDF_SO): $(SRC) src/secure_db_fields_core.h src/mysql_udf_abi_57.h
+	$(CC) $(CFLAGS) $(MYSQL_CFLAGS) -Isrc $(LDFLAGS) -o $@ $(SRC) $(LIBS)
+
+abi57: $(SRC) src/secure_db_fields_core.h src/mysql_udf_abi_57.h
+	$(CC) $(CFLAGS) -DSDF_MYSQL_UDF_ABI_57 -Isrc $(LDFLAGS) -o $(UDF_SO) $(SRC) $(LIBS)
+
+verify:
+	./bin/verify
+
+doctor:
+	MYSQL_SOCKET="$(MYSQL_SOCKET)" ./bin/doctor --mysql "$(MYSQL)" $(if $(MYSQL_DEFAULTS_FILE),--defaults-extra-file "$(MYSQL_DEFAULTS_FILE)")
+
+install: verify
+	MYSQL_SOCKET="$(MYSQL_SOCKET)" ./bin/install --mysql "$(MYSQL)" $(if $(MYSQL_DEFAULTS_FILE),--defaults-extra-file "$(MYSQL_DEFAULTS_FILE)")
+
+enable:
+	MYSQL_SOCKET="$(MYSQL_SOCKET)" ./bin/enable --mysql "$(MYSQL)" $(if $(MYSQL_DEFAULTS_FILE),--defaults-extra-file "$(MYSQL_DEFAULTS_FILE)")
+
+disable:
+	@test "$(CONFIRM)" = "DISABLE_SECURE_DB_FIELDS" || { echo 'disable requires CONFIRM=DISABLE_SECURE_DB_FIELDS' >&2; exit 2; }
+	MYSQL_SOCKET="$(MYSQL_SOCKET)" ./bin/disable --mysql "$(MYSQL)" $(if $(MYSQL_DEFAULTS_FILE),--defaults-extra-file "$(MYSQL_DEFAULTS_FILE)")
+
+status:
+	MYSQL_SOCKET="$(MYSQL_SOCKET)" ./bin/status --mysql "$(MYSQL)" $(if $(MYSQL_DEFAULTS_FILE),--defaults-extra-file "$(MYSQL_DEFAULTS_FILE)")
+
+uninstall:
+	@test "$(CONFIRM)" = "REMOVE_SECURE_DB_FIELDS" || { echo 'uninstall requires CONFIRM=REMOVE_SECURE_DB_FIELDS' >&2; exit 2; }
+	MYSQL_SOCKET="$(MYSQL_SOCKET)" ./bin/uninstall --mysql "$(MYSQL)" $(if $(MYSQL_DEFAULTS_FILE),--defaults-extra-file "$(MYSQL_DEFAULTS_FILE)")
+
+clean:
+	rm -f $(UDF_SO) *.o src/*.o

data/db_deployment/mysql/README.md

@@ -0,0 +1,33 @@
+# secure_db_fields MySQL DBA bundle
+
+This archive is produced on an application host with:
+
+```bash
+secure_db_fields db package mysql --output secure_db_fields-mysql.tar.gz --force
+```
+
+Copy the archive to the MySQL 5.7 host, extract it, then run:
+
+```bash
+make verify
+make doctor
+sudo make install
+make enable
+make status
+```
+
+Keys are not included in this archive. The DBA must provision `/etc/secure_db_fields/keys.env`
+(or set `SECURE_DB_FIELDS_KEY_FILE` for mysqld) before using decrypt/search UDFs.
+
+Installed SQL functions:
+
+- `secure_db_fields_version()`
+- `secure_db_fields_is_valid_envelope(blob)`
+- `secure_db_fields_envelope_key_id(blob)`
+- `secure_db_fields_decrypt(blob, aad)`
+- `secure_db_fields_decrypt_field(blob, table_name, column_name, row_uid)`
+- `secure_db_fields_bidx(value, domain)`
+- `secure_phone_bidx(e164)`
+- `secure_phone_prefix_bidx(e164, prefix_digits)`
+
+The readable-view pattern is display-only. Indexed search must use physical bidx columns.

data/db_deployment/mysql/bin/common

@@ -0,0 +1,199 @@
+#!/usr/bin/env bash
+
+SDF_UDF_LIBRARY='secure_db_fields_mysql.so'
+SDF_UDF_NAMES=(
+  secure_db_fields_version
+  secure_db_fields_is_valid_envelope
+  secure_db_fields_envelope_key_id
+  secure_db_fields_decrypt
+  secure_db_fields_decrypt_field
+  secure_db_fields_bidx
+  secure_phone_bidx
+  secure_phone_prefix_bidx
+)
+SDF_KEY_FILE="${SECURE_DB_FIELDS_KEY_FILE:-/etc/secure_db_fields/keys.env}"
+
+sdf_die() {
+  echo "secure_db_fields mysql: $*" >&2
+  exit 2
+}
+
+sdf_resolve_mysql() {
+  if [[ "$MYSQL" == */* ]]; then
+    [ -x "$MYSQL" ] || sdf_die "mysql client is not executable: $MYSQL"
+  else
+    MYSQL="$(command -v "$MYSQL" || true)"
+    [ -n "$MYSQL" ] || sdf_die 'mysql client was not found'
+  fi
+}
+
+sdf_mysql_args() {
+  MYSQL_ARGS=(--batch --skip-column-names --raw --protocol=SOCKET)
+  if [ -n "${DEFAULTS_FILE:-}" ]; then
+    [ -f "$DEFAULTS_FILE" ] || sdf_die "defaults file does not exist: $DEFAULTS_FILE"
+    MYSQL_ARGS=("--defaults-extra-file=$DEFAULTS_FILE" "${MYSQL_ARGS[@]}")
+  fi
+  if [ -n "${MYSQL_SOCKET:-}" ]; then
+    MYSQL_ARGS+=("--socket=$MYSQL_SOCKET")
+  fi
+}
+
+sdf_query() {
+  "$MYSQL" "${MYSQL_ARGS[@]}" -e "$1"
+}
+
+sdf_exec_file() {
+  "$MYSQL" "${MYSQL_ARGS[@]}" < "$1"
+}
+
+sdf_server_version() {
+  sdf_query 'SELECT VERSION();' | tr -d '\r\n'
+}
+
+sdf_require_mysql57() {
+  local version
+  version="$(sdf_server_version)"
+  case "$version" in
+    5.7.*) ;;
+    *) sdf_die "this bundle targets MySQL 5.7; server reports $version" ;;
+  esac
+}
+
+sdf_plugin_dir() {
+  sdf_query 'SELECT @@plugin_dir;' | tr -d '\r\n'
+}
+
+sdf_server_socket() {
+  sdf_query 'SELECT @@socket;' | tr -d '\r\n'
+}
+
+sdf_server_hostname() {
+  sdf_query 'SELECT @@hostname;' | tr -d '\r\n'
+}
+
+sdf_require_expected_socket() {
+  local actual_socket
+  actual_socket="$(sdf_server_socket)"
+  [ -n "$actual_socket" ] || sdf_die 'MySQL returned an empty @@socket'
+  if [ -n "${MYSQL_SOCKET:-}" ] && [ "$MYSQL_SOCKET" != "$actual_socket" ]; then
+    sdf_die "connected server socket $actual_socket does not match MYSQL_SOCKET $MYSQL_SOCKET"
+  fi
+}
+
+sdf_read_udf_state() {
+  local rows name dl candidate expected_name
+
+  SDF_EXPECTED_OWNED=0
+  SDF_FOREIGN_EXPECTED=0
+  SDF_UNEXPECTED_LIBRARY=0
+  SDF_REGISTERED_ROWS=()
+
+  local names_sql=""
+  local expected=()
+  for name in "${SDF_UDF_NAMES[@]}"; do
+    expected+=("'${name}'")
+  done
+  names_sql="$(IFS=,; printf '%s' "${expected[*]}")"
+
+  rows="$(sdf_query "SELECT name, dl FROM mysql.func WHERE dl = '${SDF_UDF_LIBRARY}' OR name IN (${names_sql}) ORDER BY name;")"
+  while IFS=$'\t' read -r name dl; do
+    [ -n "$name" ] || continue
+    SDF_REGISTERED_ROWS+=("$name"$'\t'"$dl")
+    expected_name=0
+    for candidate in "${SDF_UDF_NAMES[@]}"; do
+      if [ "$candidate" = "$name" ]; then expected_name=1; break; fi
+    done
+    if [ "$expected_name" -eq 1 ]; then
+      if [ "$dl" = "$SDF_UDF_LIBRARY" ]; then
+        SDF_EXPECTED_OWNED=$((SDF_EXPECTED_OWNED + 1))
+      else
+        SDF_FOREIGN_EXPECTED=$((SDF_FOREIGN_EXPECTED + 1))
+      fi
+    elif [ "$dl" = "$SDF_UDF_LIBRARY" ]; then
+      SDF_UNEXPECTED_LIBRARY=$((SDF_UNEXPECTED_LIBRARY + 1))
+    fi
+  done <<< "$rows"
+}
+
+sdf_state_is_clean_absent() {
+  [ "$SDF_EXPECTED_OWNED" -eq 0 ] && [ "$SDF_FOREIGN_EXPECTED" -eq 0 ] && [ "$SDF_UNEXPECTED_LIBRARY" -eq 0 ]
+}
+
+sdf_state_is_clean_enabled() {
+  [ "$SDF_EXPECTED_OWNED" -eq "${#SDF_UDF_NAMES[@]}" ] && [ "$SDF_FOREIGN_EXPECTED" -eq 0 ] && [ "$SDF_UNEXPECTED_LIBRARY" -eq 0 ]
+}
+
+sdf_require_clean_owned_state() {
+  if [ "$SDF_FOREIGN_EXPECTED" -ne 0 ]; then
+    sdf_die 'one or more expected UDF names are registered to a foreign SONAME; refusing to modify them'
+  fi
+  if [ "$SDF_UNEXPECTED_LIBRARY" -ne 0 ]; then
+    sdf_die "unexpected registrations reference ${SDF_UDF_LIBRARY}; refusing to modify the shared library"
+  fi
+}
+
+sdf_register_expected_udfs() {
+  sdf_exec_file "$ROOT/sql/install.sql"
+}
+
+sdf_drop_owned_udfs() {
+  local name
+  sdf_read_udf_state
+  sdf_require_clean_owned_state
+  for name in "${SDF_UDF_NAMES[@]}"; do
+    if sdf_query "SELECT COUNT(*) FROM mysql.func WHERE name = '${name}' AND dl = '${SDF_UDF_LIBRARY}';" | tr -d '\r\n' | grep -qx '1'; then
+      sdf_query "DROP FUNCTION ${name};"
+    fi
+  done
+}
+
+sdf_smoke_check() {
+  local version
+  version="$(sdf_query 'SELECT secure_db_fields_version();' | tr -d '\r\n')"
+  case "$version" in
+    *'secure_db_fields'*) ;;
+    *) sdf_die "version() smoke check failed: $version" ;;
+  esac
+}
+
+sdf_library_checksum() {
+  local library="$1"
+  if [ ! -f "$library" ]; then
+    printf '%s\n' 'missing'
+  elif command -v sha256sum >/dev/null 2>&1; then
+    sha256sum "$library" | awk '{print $1}'
+  elif command -v shasum >/dev/null 2>&1; then
+    shasum -a 256 "$library" | awk '{print $1}'
+  else
+    printf '%s\n' 'unavailable (sha256sum or shasum is required)'
+  fi
+}
+
+sdf_check_key_file_permissions() {
+  local file="${1:-$SDF_KEY_FILE}"
+  local mode
+  [ -f "$file" ] || sdf_die "key file does not exist: $file"
+  mode="$(stat -c '%a' "$file" 2>/dev/null || true)"
+  [ -n "$mode" ] || sdf_die "cannot stat key file permissions: $file"
+  if [ $((8#$mode & 0027)) -ne 0 ]; then
+    sdf_die "key file permissions are too open: $file"
+  fi
+}
+
+sdf_prepare_key_file() {
+  local dir
+  dir="$(dirname "$SDF_KEY_FILE")"
+  install -d -m 0750 -o root -g mysql "$dir"
+  if [ ! -e "$SDF_KEY_FILE" ]; then
+    install -m 0640 -o root -g mysql /dev/null "$SDF_KEY_FILE"
+  fi
+  chown root:mysql "$SDF_KEY_FILE"
+  chmod 0640 "$SDF_KEY_FILE"
+  sdf_check_key_file_permissions "$SDF_KEY_FILE"
+}
+
+sdf_build_udf() {
+  cd "$ROOT"
+  make clean >/dev/null 2>&1 || true
+  make abi57
+}

data/db_deployment/mysql/bin/disable

@@ -0,0 +1,40 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+MYSQL="${MYSQL:-mysql}"
+DEFAULTS_FILE=""
+MYSQL_SOCKET="${MYSQL_SOCKET:-}"
+
+usage() {
+  cat <<'TEXT'
+Usage: MYSQL_SOCKET=/run/mysqld/mysqld.sock ./bin/disable [--mysql PATH] [--defaults-extra-file PATH]
+
+Removes only SecureDBFields-owned UDF registrations and leaves the native library
+in place.
+TEXT
+}
+
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --mysql)
+      [ "$#" -ge 2 ] || { echo '--mysql requires a path' >&2; exit 2; }
+      MYSQL="$2"; shift 2 ;;
+    --defaults-extra-file)
+      [ "$#" -ge 2 ] || { echo '--defaults-extra-file requires a path' >&2; exit 2; }
+      DEFAULTS_FILE="$2"; shift 2 ;;
+    --help|-h)
+      usage; exit 0 ;;
+    *)
+      echo "secure_db_fields mysql disable: unknown option: $1" >&2; exit 2 ;;
+  esac
+done
+
+source "$ROOT/bin/common"
+sdf_resolve_mysql
+sdf_mysql_args
+sdf_require_mysql57
+sdf_require_expected_socket
+sdf_drop_owned_udfs
+
+echo 'SecureDBFields MySQL UDFs are disabled.'

data/db_deployment/mysql/bin/doctor

@@ -0,0 +1,57 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+MYSQL="${MYSQL:-mysql}"
+DEFAULTS_FILE=""
+MYSQL_SOCKET="${MYSQL_SOCKET:-}"
+
+usage() {
+  cat <<'TEXT'
+Usage: MYSQL_SOCKET=/run/mysqld/mysqld.sock ./bin/doctor [--mysql PATH] [--defaults-extra-file PATH]
+
+Run this on the MySQL 5.7 host. The bundle uses a local Unix socket so the UDF
+library is installed into the plugin_dir of that same mysqld.
+TEXT
+}
+
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --mysql)
+      [ "$#" -ge 2 ] || { echo '--mysql requires a path' >&2; exit 2; }
+      MYSQL="$2"; shift 2 ;;
+    --defaults-extra-file)
+      [ "$#" -ge 2 ] || { echo '--defaults-extra-file requires a path' >&2; exit 2; }
+      DEFAULTS_FILE="$2"; shift 2 ;;
+    --help|-h)
+      usage; exit 0 ;;
+    *)
+      echo "secure_db_fields mysql doctor: unknown option: $1" >&2; exit 2 ;;
+  esac
+done
+
+source "$ROOT/bin/common"
+sdf_resolve_mysql
+sdf_mysql_args
+command -v make >/dev/null 2>&1 || sdf_die 'make is required'
+command -v cc >/dev/null 2>&1 || sdf_die 'a C compiler is required (cc/gcc/clang)'
+sdf_require_mysql57
+sdf_require_expected_socket
+
+PLUGIN_DIR="$(sdf_plugin_dir)"
+SERVER_SOCKET="$(sdf_server_socket)"
+SERVER_HOSTNAME="$(sdf_server_hostname)"
+[ -n "$PLUGIN_DIR" ] || sdf_die 'MySQL returned an empty @@plugin_dir'
+[ -d "$PLUGIN_DIR" ] || sdf_die "@@plugin_dir is not a local directory: $PLUGIN_DIR"
+if [ -e "$SDF_KEY_FILE" ]; then
+  sdf_check_key_file_permissions "$SDF_KEY_FILE"
+fi
+
+printf '%s\n' \
+  "MySQL: $(sdf_server_version)" \
+  "mysql client: $MYSQL" \
+  "server hostname: $SERVER_HOSTNAME" \
+  "server socket: $SERVER_SOCKET" \
+  "plugin directory: $PLUGIN_DIR" \
+  "bundle: $ROOT" \
+  'doctor: OK'

data/db_deployment/mysql/bin/enable

@@ -0,0 +1,56 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+MYSQL="${MYSQL:-mysql}"
+DEFAULTS_FILE=""
+MYSQL_SOCKET="${MYSQL_SOCKET:-}"
+
+usage() {
+  cat <<'TEXT'
+Usage: MYSQL_SOCKET=/run/mysqld/mysqld.sock ./bin/enable [--mysql PATH] [--defaults-extra-file PATH]
+
+Registers the SecureDBFields UDFs once. Existing healthy registrations are left
+untouched; this command never drops functions automatically.
+TEXT
+}
+
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --mysql)
+      [ "$#" -ge 2 ] || { echo '--mysql requires a path' >&2; exit 2; }
+      MYSQL="$2"; shift 2 ;;
+    --defaults-extra-file)
+      [ "$#" -ge 2 ] || { echo '--defaults-extra-file requires a path' >&2; exit 2; }
+      DEFAULTS_FILE="$2"; shift 2 ;;
+    --help|-h)
+      usage; exit 0 ;;
+    *)
+      echo "secure_db_fields mysql enable: unknown option: $1" >&2; exit 2 ;;
+  esac
+done
+
+source "$ROOT/bin/common"
+sdf_resolve_mysql
+sdf_mysql_args
+sdf_require_mysql57
+sdf_require_expected_socket
+sdf_read_udf_state
+
+if sdf_state_is_clean_absent; then
+  sdf_register_expected_udfs
+  sdf_read_udf_state
+  sdf_state_is_clean_enabled || sdf_die 'registration did not create the expected UDF state'
+  sdf_smoke_check
+  echo 'SecureDBFields MySQL UDFs are enabled. Apply generated admin-view SQL separately.'
+  exit 0
+fi
+
+if sdf_state_is_clean_enabled; then
+  sdf_smoke_check
+  echo 'SecureDBFields MySQL UDFs are already enabled; no changes made.'
+  exit 0
+fi
+
+sdf_require_clean_owned_state
+sdf_die 'UDF registrations are partial; run make status and resolve the state before enabling'

data/db_deployment/mysql/bin/install

@@ -0,0 +1,64 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+MYSQL="${MYSQL:-mysql}"
+DEFAULTS_FILE=""
+MYSQL_SOCKET="${MYSQL_SOCKET:-}"
+
+usage() {
+  cat <<'TEXT'
+Usage: sudo MYSQL_SOCKET=/run/mysqld/mysqld.sock ./bin/install [--mysql PATH] [--defaults-extra-file PATH]
+
+Builds and installs a fresh MySQL 5.7 UDF library. It refuses to replace a
+library while any expected UDF is registered; use ./bin/uninstall first.
+TEXT
+}
+
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --mysql)
+      [ "$#" -ge 2 ] || { echo '--mysql requires a path' >&2; exit 2; }
+      MYSQL="$2"; shift 2 ;;
+    --defaults-extra-file)
+      [ "$#" -ge 2 ] || { echo '--defaults-extra-file requires a path' >&2; exit 2; }
+      DEFAULTS_FILE="$2"; shift 2 ;;
+    --help|-h)
+      usage; exit 0 ;;
+    *)
+      echo "secure_db_fields mysql install: unknown option: $1" >&2; exit 2 ;;
+  esac
+done
+
+[ "${EUID:-$(id -u)}" -eq 0 ] || { echo 'secure_db_fields mysql install: run as root: sudo ./bin/install ...' >&2; exit 2; }
+DOCTOR_ARGS=(--mysql "$MYSQL")
+if [ -n "$DEFAULTS_FILE" ]; then
+  DOCTOR_ARGS+=(--defaults-extra-file "$DEFAULTS_FILE")
+fi
+MYSQL_SOCKET="$MYSQL_SOCKET" "$ROOT/bin/doctor" "${DOCTOR_ARGS[@]}"
+
+source "$ROOT/bin/common"
+sdf_resolve_mysql
+sdf_mysql_args
+sdf_prepare_key_file
+sdf_read_udf_state
+if ! sdf_state_is_clean_absent; then
+  sdf_die 'fresh install refuses to replace a library while UDF registrations exist; run status or uninstall first'
+fi
+
+PLUGIN_DIR="$(sdf_plugin_dir)"
+TEMP_LIBRARY="$PLUGIN_DIR/.${SDF_UDF_LIBRARY}.$$.$RANDOM.tmp"
+trap 'rm -f "$TEMP_LIBRARY"' EXIT
+
+sdf_build_udf
+install -d -m 0755 "$PLUGIN_DIR"
+install -m 0755 "$ROOT/$SDF_UDF_LIBRARY" "$TEMP_LIBRARY"
+mv -f "$TEMP_LIBRARY" "$PLUGIN_DIR/$SDF_UDF_LIBRARY"
+trap - EXIT
+
+printf '%s\n' \
+  'SecureDBFields MySQL UDF library installed.' \
+  "  library: $PLUGIN_DIR/$SDF_UDF_LIBRARY" \
+  '' \
+  'Register the UDFs once on this MySQL server:' \
+  '  make enable'

data/db_deployment/mysql/bin/status

@@ -0,0 +1,11 @@
+#!/usr/bin/env bash
+set -euo pipefail
+source "$(dirname "$0")/common"
+
+printf 'plugin_dir=%s\n' "$(plugin_dir)"
+printf 'registered_functions=%s\n' "$(function_count)"
+if mysql_cmd -e 'SELECT secure_db_fields_version() AS version;' >/dev/null 2>&1; then
+  mysql_cmd -e 'SELECT secure_db_fields_version() AS version;'
+else
+  echo 'secure_db_fields_version() is not enabled'
+fi