tranfi 0.0.2 → 0.2.0

package/csrc/size_utils.c

@@ -0,0 +1,348 @@
+/*
+ * size_utils.c -- checked size arithmetic and JSON size arguments.
+ */
+
+#if defined(__linux__) && !defined(_GNU_SOURCE)
+#define _GNU_SOURCE
+#endif
+
+#include "internal.h"
+#include "cJSON.h"
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+
+int tf_format_float64(char *buf, size_t buf_size, double value) {
+    if (!buf || buf_size == 0) return TF_ERROR;
+    int n = snprintf(buf, buf_size, TF_FLOAT64_ROUNDTRIP_FORMAT, value);
+    if (n < 0 || (size_t)n >= buf_size) return TF_ERROR;
+    return TF_OK;
+}
+
+int tf_size_add(size_t a, size_t b, size_t *out) {
+    if (!out) return TF_ERROR;
+    if (a > SIZE_MAX - b) return TF_ERROR;
+    *out = a + b;
+    return TF_OK;
+}
+
+int tf_size_mul(size_t a, size_t b, size_t *out) {
+    if (!out) return TF_ERROR;
+    if (a != 0 && b > SIZE_MAX / a) return TF_ERROR;
+    *out = a * b;
+    return TF_OK;
+}
+
+int tf_size_align(size_t x, size_t align, size_t *out) {
+    if (!out || align == 0) return TF_ERROR;
+    size_t rem = x % align;
+    if (rem == 0) {
+        *out = x;
+        return TF_OK;
+    }
+    return tf_size_add(x, align - rem, out);
+}
+
+int tf_size_grow_pow2(size_t current, size_t min_value, size_t min_capacity, size_t *out) {
+    if (!out) return TF_ERROR;
+    size_t cap = current ? current : min_capacity;
+    if (cap == 0) cap = 1;
+    while (cap < min_value) {
+        if (cap > SIZE_MAX / 2) return TF_ERROR;
+        cap *= 2;
+    }
+    *out = cap;
+    return TF_OK;
+}
+
+void *tf_mallocarray_checked(size_t count, size_t elem_size) {
+    size_t bytes = 0;
+    if (tf_size_mul(count, elem_size, &bytes) != TF_OK) return NULL;
+    if (bytes == 0) bytes = 1;
+    return malloc(bytes);
+}
+
+void *tf_callocarray_checked(size_t count, size_t elem_size) {
+    if (count == 0 || elem_size == 0) return calloc(1, 1);
+    size_t bytes = 0;
+    if (tf_size_mul(count, elem_size, &bytes) != TF_OK) return NULL;
+    return calloc(1, bytes);
+}
+
+void *tf_reallocarray_checked(void *ptr, size_t count, size_t elem_size) {
+    size_t bytes = 0;
+    if (tf_size_mul(count, elem_size, &bytes) != TF_OK) return NULL;
+    if (bytes == 0) bytes = 1;
+    return realloc(ptr, bytes);
+}
+
+char *tf_strdup_checked(const char *s) {
+    const char *src = s ? s : "";
+    size_t len = strlen(src);
+    size_t bytes = 0;
+    if (tf_size_add(len, 1, &bytes) != TF_OK) return NULL;
+    char *copy = tf_mallocarray_checked(bytes, sizeof(char));
+    if (!copy) return NULL;
+    memcpy(copy, src, bytes);
+    return copy;
+}
+
+char *tf_string_append_suffix_checked(const char *prefix, const char *suffix) {
+    const char *a = prefix ? prefix : "";
+    const char *b = suffix ? suffix : "";
+    size_t a_len = strlen(a);
+    size_t b_len = strlen(b);
+    size_t text_len = 0;
+    size_t bytes = 0;
+    if (tf_size_add(a_len, b_len, &text_len) != TF_OK ||
+        tf_size_add(text_len, 1, &bytes) != TF_OK) return NULL;
+    char *copy = tf_mallocarray_checked(bytes, sizeof(char));
+    if (!copy) return NULL;
+    memcpy(copy, a, a_len);
+    memcpy(copy + a_len, b, b_len);
+    copy[text_len] = '\0';
+    return copy;
+}
+
+static void tf_index_swap(size_t *a, size_t *b) {
+    size_t tmp = *a;
+    *a = *b;
+    *b = tmp;
+}
+
+static void tf_sort_indices_sift_down(size_t *indices, size_t start, size_t end,
+                                      tf_index_compare_fn compare, const void *ctx) {
+    size_t root = start;
+    while (root <= (end - 1) / 2) {
+        size_t child = root * 2 + 1;
+        size_t swap_idx = root;
+        if (compare(ctx, indices[swap_idx], indices[child]) < 0) {
+            swap_idx = child;
+        }
+        if (child + 1 <= end &&
+            compare(ctx, indices[swap_idx], indices[child + 1]) < 0) {
+            swap_idx = child + 1;
+        }
+        if (swap_idx == root) return;
+        tf_index_swap(&indices[root], &indices[swap_idx]);
+        root = swap_idx;
+    }
+}
+
+static void tf_sort_indices_heap_range(size_t *indices, size_t n,
+                                       tf_index_compare_fn compare, const void *ctx) {
+    size_t start = (n - 2) / 2 + 1;
+    while (start > 0) {
+        start--;
+        tf_sort_indices_sift_down(indices, start, n - 1, compare, ctx);
+    }
+
+    size_t end = n - 1;
+    while (end > 0) {
+        tf_index_swap(&indices[0], &indices[end]);
+        end--;
+        if (end > 0) tf_sort_indices_sift_down(indices, 0, end, compare, ctx);
+    }
+}
+
+static void tf_sort_indices_insertion_range(size_t *indices, size_t lo, size_t hi,
+                                            tf_index_compare_fn compare, const void *ctx) {
+    for (size_t i = lo + 1; i < hi; i++) {
+        size_t v = indices[i];
+        size_t j = i;
+        while (j > lo && compare(ctx, v, indices[j - 1]) < 0) {
+            indices[j] = indices[j - 1];
+            j--;
+        }
+        indices[j] = v;
+    }
+}
+
+static size_t tf_sort_indices_median3(size_t *indices, size_t a, size_t b, size_t c,
+                                      tf_index_compare_fn compare, const void *ctx) {
+    size_t va = indices[a];
+    size_t vb = indices[b];
+    size_t vc = indices[c];
+
+    if (compare(ctx, va, vb) < 0) {
+        if (compare(ctx, vb, vc) < 0) return vb;
+        return compare(ctx, va, vc) < 0 ? vc : va;
+    }
+    if (compare(ctx, va, vc) < 0) return va;
+    return compare(ctx, vb, vc) < 0 ? vc : vb;
+}
+
+static size_t tf_sort_indices_partition(size_t *indices, size_t lo, size_t hi, size_t pivot,
+                                        tf_index_compare_fn compare, const void *ctx) {
+    size_t i = lo;
+    size_t j = hi;
+    for (;;) {
+        while (compare(ctx, indices[i], pivot) < 0) i++;
+        do {
+            j--;
+        } while (compare(ctx, pivot, indices[j]) < 0);
+        if (i >= j) return i;
+        tf_index_swap(&indices[i], &indices[j]);
+        i++;
+    }
+}
+
+static size_t tf_sort_indices_depth_limit(size_t n) {
+    size_t depth = 0;
+    while (n > 1) {
+        depth++;
+        n >>= 1;
+    }
+    return depth * 2;
+}
+
+static void tf_sort_indices_intro_loop(size_t *indices, size_t lo, size_t hi, size_t depth_limit,
+                                       tf_index_compare_fn compare, const void *ctx) {
+    enum { INSERTION_THRESHOLD = 16 };
+
+    while (hi - lo > INSERTION_THRESHOLD) {
+        if (depth_limit == 0) {
+            tf_sort_indices_heap_range(indices + lo, hi - lo, compare, ctx);
+            return;
+        }
+        depth_limit--;
+
+        size_t mid = lo + (hi - lo) / 2;
+        size_t pivot = tf_sort_indices_median3(indices, lo, mid, hi - 1, compare, ctx);
+        size_t cut = tf_sort_indices_partition(indices, lo, hi, pivot, compare, ctx);
+        if (cut <= lo || cut >= hi) {
+            tf_sort_indices_heap_range(indices + lo, hi - lo, compare, ctx);
+            return;
+        }
+
+        if (cut - lo < hi - cut) {
+            tf_sort_indices_intro_loop(indices, lo, cut, depth_limit, compare, ctx);
+            lo = cut;
+        } else {
+            tf_sort_indices_intro_loop(indices, cut, hi, depth_limit, compare, ctx);
+            hi = cut;
+        }
+    }
+    tf_sort_indices_insertion_range(indices, lo, hi, compare, ctx);
+}
+
+typedef struct {
+    tf_index_compare_fn compare;
+    const void *ctx;
+} tf_sort_indices_qsort_ctx;
+
+static int tf_sort_indices_total_compare(const void *ctx, size_t ia, size_t ib) {
+    const tf_sort_indices_qsort_ctx *qctx = (const tf_sort_indices_qsort_ctx *)ctx;
+    int result = qctx->compare(qctx->ctx, ia, ib);
+    if (result != 0) return result;
+    return ia < ib ? -1 : ia > ib ? 1 : 0;
+}
+
+#if defined(__GLIBC__)
+static int tf_sort_indices_qsort_compare_glibc(const void *a, const void *b, void *thunk) {
+    const tf_sort_indices_qsort_ctx *qctx = (const tf_sort_indices_qsort_ctx *)thunk;
+    size_t ia = *(const size_t *)a;
+    size_t ib = *(const size_t *)b;
+    return tf_sort_indices_total_compare(qctx, ia, ib);
+}
+#elif defined(__APPLE__) || defined(__FreeBSD__) || defined(__OpenBSD__) || defined(__NetBSD__)
+static int tf_sort_indices_qsort_compare_bsd(void *thunk, const void *a, const void *b) {
+    const tf_sort_indices_qsort_ctx *qctx = (const tf_sort_indices_qsort_ctx *)thunk;
+    size_t ia = *(const size_t *)a;
+    size_t ib = *(const size_t *)b;
+    return tf_sort_indices_total_compare(qctx, ia, ib);
+}
+#endif
+
+void tf_sort_indices(size_t *indices, size_t n, tf_index_compare_fn compare, const void *ctx) {
+    if (!indices || !compare || n < 2) return;
+
+#if defined(__GLIBC__)
+    tf_sort_indices_qsort_ctx qctx = { compare, ctx };
+    qsort_r(indices, n, sizeof(size_t), tf_sort_indices_qsort_compare_glibc, &qctx);
+#elif defined(__APPLE__) || defined(__FreeBSD__) || defined(__OpenBSD__) || defined(__NetBSD__)
+    tf_sort_indices_qsort_ctx qctx = { compare, ctx };
+    qsort_r(indices, n, sizeof(size_t), &qctx, tf_sort_indices_qsort_compare_bsd);
+#else
+    tf_sort_indices_qsort_ctx qctx = { compare, ctx };
+    tf_sort_indices_intro_loop(indices, 0, n, tf_sort_indices_depth_limit(n),
+                               tf_sort_indices_total_compare, &qctx);
+#endif
+}
+
+int tf_check_byte_limit(size_t n, size_t max_value,
+                        const char *context, const char *name) {
+    if (n <= max_value) return TF_OK;
+    char msg[256];
+    snprintf(msg, sizeof(msg), "%s: %s exceeds maximum %zu bytes",
+             context ? context : "size", name ? name : "value", max_value);
+    tf_set_last_error(msg);
+    return TF_ERROR;
+}
+
+int tf_string_length_bounded(const char *s, size_t max_value,
+                             size_t *out, const char *context,
+                             const char *name) {
+    if (!s || !out) return TF_ERROR;
+    for (size_t i = 0; ; i++) {
+        if (s[i] == '\0') {
+            *out = i;
+            return TF_OK;
+        }
+        if (i == max_value) break;
+    }
+    return tf_check_byte_limit(max_value == SIZE_MAX ? SIZE_MAX : max_value + 1,
+                               max_value, context, name);
+}
+
+int tf_json_size_value(const cJSON *item, const char *name,
+                       size_t min_value, size_t max_value,
+                       size_t *out, const char *context) {
+    if (!out) return -1;
+    if (!item) return 0;
+    double d = item->valuedouble;
+    if (!cJSON_IsNumber(item) || !(d >= 0.0) ||
+        d < (double)min_value || d > (double)max_value) {
+        char msg[256];
+        snprintf(msg, sizeof(msg), "%s: %s must be an integer between %zu and %zu",
+                 context ? context : "argument", name, min_value, max_value);
+        tf_set_last_error(msg);
+        return -1;
+    }
+    size_t parsed = (size_t)d;
+    if ((double)parsed != d) {
+        char msg[256];
+        snprintf(msg, sizeof(msg), "%s: %s must be an integer between %zu and %zu",
+                 context ? context : "argument", name, min_value, max_value);
+        tf_set_last_error(msg);
+        return -1;
+    }
+    *out = parsed;
+    return 1;
+}
+
+int tf_json_get_size_arg(const cJSON *args, const char *name,
+                         size_t min_value, size_t max_value,
+                         size_t *out, const char *context) {
+    if (!out) return -1;
+    if (!args || !name) return 0;
+    const cJSON *item = cJSON_GetObjectItemCaseSensitive(args, name);
+    if (!item) return 0;
+    return tf_json_size_value(item, name, min_value, max_value, out, context);
+}
+
+int tf_json_get_size_arg_any(const cJSON *args, const char *name,
+                             const char *alt_name,
+                             size_t min_value, size_t max_value,
+                             size_t *out, const char *context) {
+    if (!out) return -1;
+    if (!args || !name) return 0;
+    const cJSON *item = cJSON_GetObjectItemCaseSensitive(args, name);
+    const char *used_name = name;
+    if (!item && alt_name) {
+        item = cJSON_GetObjectItemCaseSensitive(args, alt_name);
+        used_name = alt_name;
+    }
+    if (!item) return 0;
+    return tf_json_size_value(item, used_name, min_value, max_value, out, context);
+}

package/csrc/spill.c

@@ -0,0 +1,317 @@
+/*
+ * spill.c -- secure spill session implementation.
+ */
+
+#include "spill.h"
+#include "internal.h"
+
+#ifdef __EMSCRIPTEN__
+
+int tf_spill_session_create(const char *root, tf_spill_session **out) {
+    (void)root;
+    if (out) *out = NULL;
+    tf_set_last_error("spill is not supported in WASM");
+    return TF_ERROR;
+}
+
+int tf_spill_open_run(tf_spill_session *s, const char *label, int *fd, char **path_out) {
+    (void)s; (void)label;
+    if (fd) *fd = -1;
+    if (path_out) *path_out = NULL;
+    tf_set_last_error("spill is not supported in WASM");
+    return TF_ERROR;
+}
+
+FILE *tf_spill_open_run_file(tf_spill_session *s, const char *label, char **path_out) {
+    (void)s; (void)label;
+    if (path_out) *path_out = NULL;
+    tf_set_last_error("spill is not supported in WASM");
+    return NULL;
+}
+
+int tf_spill_cleanup(tf_spill_session *s) {
+    (void)s;
+    return TF_OK;
+}
+
+#else
+
+#include <errno.h>
+#include <fcntl.h>
+#include <stdint.h>
+#include <stdatomic.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <sys/stat.h>
+#include <sys/types.h>
+#include <time.h>
+#include <unistd.h>
+
+#ifndef O_CLOEXEC
+#define O_CLOEXEC 0
+#endif
+#ifndef O_DIRECTORY
+#define O_DIRECTORY 0
+#endif
+#ifndef O_NOFOLLOW
+#define O_NOFOLLOW 0
+#endif
+
+struct tf_spill_session {
+    int     dirfd;
+    char   *path;
+    char  **names;
+    size_t  n_names;
+    size_t  cap_names;
+    size_t  seq;
+};
+
+static void set_spill_errno(const char *prefix, const char *path) {
+    char msg[512];
+    snprintf(msg, sizeof(msg), "%s '%s': %s", prefix, path ? path : "", strerror(errno));
+    tf_set_last_error(msg);
+}
+
+static uint64_t random_u64(void) {
+    uint64_t v = 0;
+    int fd = open("/dev/urandom", O_RDONLY | O_CLOEXEC);
+    if (fd >= 0) {
+        ssize_t n = read(fd, &v, sizeof(v));
+        close(fd);
+        if (n == (ssize_t)sizeof(v)) return v;
+    }
+    static atomic_uint_fast64_t counter = 0;
+    uint64_t c = (uint64_t)atomic_fetch_add_explicit(&counter, 1, memory_order_relaxed) + 1u;
+    v = (uint64_t)time(NULL);
+    v ^= ((uint64_t)getpid()) << 32;
+    v ^= (uint64_t)(uintptr_t)&v;
+    v ^= c * UINT64_C(0x9e3779b97f4a7c15);
+    return v;
+}
+
+static int append_name(tf_spill_session *s, char *name) {
+    if (s->n_names == s->cap_names) {
+        size_t need = 0;
+        size_t new_cap = 0;
+        if (tf_size_add(s->n_names, 1, &need) != TF_OK ||
+            tf_size_grow_pow2(s->cap_names, need, 16, &new_cap) != TF_OK) {
+            return TF_ERROR;
+        }
+        char **tmp = tf_reallocarray_checked(s->names, new_cap, sizeof(char *));
+        if (!tmp) return TF_ERROR;
+        s->names = tmp;
+        s->cap_names = new_cap;
+    }
+    s->names[s->n_names++] = name;
+    return TF_OK;
+}
+
+static char *join_path(const char *dir, const char *name) {
+    size_t dlen = strlen(dir);
+    size_t nlen = strlen(name);
+    int need_sep = dlen > 0 && dir[dlen - 1] != '/';
+    char *path = malloc(dlen + (need_sep ? 1u : 0u) + nlen + 1u);
+    if (!path) return NULL;
+    memcpy(path, dir, dlen);
+    size_t off = dlen;
+    if (need_sep) path[off++] = '/';
+    memcpy(path + off, name, nlen + 1u);
+    return path;
+}
+
+static void sanitize_label(const char *label, char out[32]) {
+    size_t j = 0;
+    if (!label || !label[0]) label = "run";
+    for (size_t i = 0; label[i] && j < 31; i++) {
+        unsigned char ch = (unsigned char)label[i];
+        if ((ch >= 'a' && ch <= 'z') || (ch >= 'A' && ch <= 'Z') ||
+            (ch >= '0' && ch <= '9') || ch == '-' || ch == '_') {
+            out[j++] = (char)ch;
+        } else {
+            out[j++] = '-';
+        }
+    }
+    if (j == 0) out[j++] = 'r';
+    out[j] = '\0';
+}
+
+static int validate_root_fd(int fd, const char *root) {
+    struct stat st;
+    if (fstat(fd, &st) != 0) {
+        set_spill_errno("spill: cannot stat root", root);
+        return TF_ERROR;
+    }
+    if (!S_ISDIR(st.st_mode)) {
+        tf_set_last_error("spill: root is not a directory");
+        return TF_ERROR;
+    }
+#ifdef S_ISVTX
+    if ((st.st_mode & S_IWOTH) && !(st.st_mode & S_ISVTX)) {
+#else
+    if (st.st_mode & S_IWOTH) {
+#endif
+        tf_set_last_error("spill: root is world-writable without sticky bit");
+        return TF_ERROR;
+    }
+    if (st.st_uid != geteuid()) {
+        tf_set_last_error("spill: root is not owned by the current user");
+        return TF_ERROR;
+    }
+    return TF_OK;
+}
+
+int tf_spill_session_create(const char *root, tf_spill_session **out) {
+    if (!out) {
+        tf_set_last_error("spill: output session pointer is required");
+        return TF_ERROR;
+    }
+    *out = NULL;
+    if (!root || !root[0]) {
+        tf_set_last_error("spill: root directory is required");
+        return TF_ERROR;
+    }
+
+    int rootfd = open(root, O_RDONLY | O_DIRECTORY | O_CLOEXEC | O_NOFOLLOW);
+    if (rootfd < 0) {
+        set_spill_errno("spill: cannot open root", root);
+        return TF_ERROR;
+    }
+    if (validate_root_fd(rootfd, root) != TF_OK) {
+        close(rootfd);
+        return TF_ERROR;
+    }
+
+    tf_spill_session *s = calloc(1, sizeof(*s));
+    if (!s) {
+        close(rootfd);
+        tf_set_last_error("spill: out of memory");
+        return TF_ERROR;
+    }
+    s->dirfd = -1;
+
+    char name[96];
+    int created = 0;
+    for (int attempt = 0; attempt < 128; attempt++) {
+        snprintf(name, sizeof(name), "tranfi-spill-%016llx-%016llx",
+                 (unsigned long long)random_u64(), (unsigned long long)random_u64());
+        if (mkdirat(rootfd, name, 0700) == 0) {
+            created = 1;
+            break;
+        }
+        if (errno != EEXIST) {
+            set_spill_errno("spill: cannot create private directory under", root);
+            close(rootfd);
+            free(s);
+            return TF_ERROR;
+        }
+    }
+    if (!created) {
+        tf_set_last_error("spill: could not allocate a unique private directory");
+        close(rootfd);
+        free(s);
+        return TF_ERROR;
+    }
+
+    s->path = join_path(root, name);
+    if (!s->path) {
+        unlinkat(rootfd, name, AT_REMOVEDIR);
+        close(rootfd);
+        free(s);
+        tf_set_last_error("spill: out of memory");
+        return TF_ERROR;
+    }
+    s->dirfd = openat(rootfd, name, O_RDONLY | O_DIRECTORY | O_CLOEXEC | O_NOFOLLOW);
+    close(rootfd);
+    if (s->dirfd < 0) {
+        set_spill_errno("spill: cannot open private directory", s->path);
+        rmdir(s->path);
+        free(s->path);
+        free(s);
+        return TF_ERROR;
+    }
+    (void)fchmod(s->dirfd, 0700);
+    if (out) *out = s;
+    return TF_OK;
+}
+
+int tf_spill_open_run(tf_spill_session *s, const char *label, int *fd, char **path_out) {
+    if (fd) *fd = -1;
+    if (path_out) *path_out = NULL;
+    if (!s || s->dirfd < 0) {
+        tf_set_last_error("spill: invalid spill session");
+        return TF_ERROR;
+    }
+
+    char clean[32];
+    sanitize_label(label, clean);
+    for (int attempt = 0; attempt < 128; attempt++) {
+        char name_buf[128];
+        snprintf(name_buf, sizeof(name_buf), "%s-%zu-%016llx.bin",
+                 clean, s->seq++, (unsigned long long)random_u64());
+        int runfd = openat(s->dirfd, name_buf,
+                           O_WRONLY | O_CREAT | O_EXCL | O_NOFOLLOW | O_CLOEXEC,
+                           0600);
+        if (runfd < 0) {
+            if (errno == EEXIST) continue;
+            set_spill_errno("spill: cannot create run", name_buf);
+            return TF_ERROR;
+        }
+        char *tracked = strdup(name_buf);
+        char *path = join_path(s->path, name_buf);
+        if (!tracked || !path || append_name(s, tracked) != TF_OK) {
+            close(runfd);
+            unlinkat(s->dirfd, name_buf, 0);
+            free(tracked);
+            free(path);
+            tf_set_last_error("spill: out of memory");
+            return TF_ERROR;
+        }
+        if (fd) *fd = runfd;
+        else close(runfd);
+        if (path_out) *path_out = path;
+        else free(path);
+        return TF_OK;
+    }
+    tf_set_last_error("spill: could not allocate a unique run file");
+    return TF_ERROR;
+}
+
+FILE *tf_spill_open_run_file(tf_spill_session *s, const char *label, char **path_out) {
+    int fd = -1;
+    char *path = NULL;
+    if (tf_spill_open_run(s, label, &fd, &path) != TF_OK) return NULL;
+    FILE *f = fdopen(fd, "wb");
+    if (!f) {
+        char msg[512];
+        snprintf(msg, sizeof(msg), "spill: cannot fdopen run '%s': %s", path ? path : "", strerror(errno));
+        tf_set_last_error(msg);
+        close(fd);
+        if (path) remove(path);
+        free(path);
+        if (path_out) *path_out = NULL;
+        return NULL;
+    }
+    if (path_out) *path_out = path;
+    else free(path);
+    return f;
+}
+
+int tf_spill_cleanup(tf_spill_session *s) {
+    if (!s) return TF_OK;
+    int rc = TF_OK;
+    if (s->dirfd >= 0) {
+        for (size_t i = 0; i < s->n_names; i++) {
+            if (s->names[i] && unlinkat(s->dirfd, s->names[i], 0) != 0 && errno != ENOENT) rc = TF_ERROR;
+        }
+        close(s->dirfd);
+    }
+    for (size_t i = 0; i < s->n_names; i++) free(s->names[i]);
+    free(s->names);
+    if (s->path && rmdir(s->path) != 0 && errno != ENOENT) rc = TF_ERROR;
+    free(s->path);
+    free(s);
+    return rc;
+}
+
+#endif

package/csrc/spill.h

@@ -0,0 +1,21 @@
+/*
+ * spill.h -- internal secure spill-file helper.
+ *
+ * Spill users create one private session directory under a host-approved root,
+ * then create individual run files inside it with exclusive openat().
+ */
+
+#ifndef TF_SPILL_H
+#define TF_SPILL_H
+
+#include "tranfi.h"
+#include <stdio.h>
+
+typedef struct tf_spill_session tf_spill_session;
+
+int   tf_spill_session_create(const char *root, tf_spill_session **out);
+int   tf_spill_open_run(tf_spill_session *s, const char *label, int *fd, char **path_out);
+FILE *tf_spill_open_run_file(tf_spill_session *s, const char *label, char **path_out);
+int   tf_spill_cleanup(tf_spill_session *s);
+
+#endif