Sulkta-Coop/clawdforge
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
clawdforge/clients/c/include/clawdforge.h
Kayos 70f4dcc2a4 clients/c: apply audit findings — security + CVE bump (a69e924 → new) 
HIGH:
- H1: enlarge test base_with_slash buffer 64 → 80; cmake --build now
  clean under -Werror=format-truncation.
- H2: CURLOPT_FOLLOWLOCATION = 0 (no cross-host bearer leak; SDK talks
  to a known endpoint, redirects unexpected). MAXREDIRS dropped.
- H3: cf_admin_revoke_token validates name [A-Za-z0-9_-]+ client-side
  before URL build; rejects "a/../healthz" with CF_ERR_USAGE before
  the request leaves the process.

MEDIUM:
- M1: cf_buf_append overflow guards — n + len + 1 wrap-check up front;
  newcap *= 2 doubling-loop bounded by SIZE_MAX/2.
- M2: 64 MiB CF_MAX_RESPONSE_BYTES cap exposed on the public header;
  write_cb aborts the transfer once exceeded → CF_ERR_TRANSPORT.
- M3: CURLOPT_CONNECTTIMEOUT_MS = 10000 (was implicit 300s default).
- M4: g_curl_init_count is now _Atomic int (C11 stdatomic) using
  atomic_fetch_add/sub; concurrent cf_client_new/cf_client_free across
  threads no longer races the libcurl global init/cleanup transition.

LOW:
- L1: push_auth propagates CF_ERR_OOM via an out-param instead of
  silently dropping the Authorization header (which previously surfaced
  as a misleading 401 from the server).
- L2: write_cb size*nmemb overflow defensive guard.

CVE:
- Bump vendored cJSON 1.7.15 → 1.7.18 (fixes CVE-2024-31755:
  cJSON_SetValuestring NULL-deref). cJSON.c/cJSON.h replaced from
  upstream tag v1.7.18; LICENSE file unchanged. README updated.

Tests added (15 → 21):
- test_revoke_token_validates_name: path-traversal name rejected,
  valid name proceeds through to transport.
- test_buf_append_overflow_guards: synthetic SIZE_MAX-edge inputs
  trigger error-return rather than wrap.
- test_response_body_size_cap: mock streams 65 MiB; client aborts
  with CF_ERR_TRANSPORT.
- test_connect_timeout: dial 10.255.255.1, assert <18s wallclock
  (vs. libcurl's 300s default).
- test_concurrent_client_init: 4 pthreads × 50 iters, no crash, no
  leak under valgrind.
- test_cjson_bump: cJSON_SetValuestring(node, NULL) returns NULL
  safely; malformed cJSON_Parse returns NULL.

Verification:
- cmake --build build (Release): clean
- ctest --test-dir build: 21/21 pass (incl. 10s connect-timeout test)
- ctest --test-dir build-asan (ASan + UBSan): clean
- valgrind --leak-check=full: 10,313 allocs == 10,313 frees, 0 errors,
  0 leaks

README updated: cJSON 1.7.18 note, C11 + stdatomic requirement.

Audit: memory/clawdforge-audits/c-a69e924.md
2026-04-28 23:25:22 -07:00

289 lines
11 KiB
C
Raw Blame History

/*
* clawdforge — C SDK
*
* MIT License — see CMakeLists.txt for the full text.
*
* A small synchronous C client for the clawdforge HTTP service.
* The service wraps `claude -p` subprocess calls behind a
* bearer-token-gated REST API.
*
* Single public header. The client struct (cf_client_t) is opaque;
* callers only ever see a forward-declared typedef and a set of
* functions that take it.
*
* Threading: cf_client_t is NOT shared across threads. Create one
* client per thread (or guard one client with your own mutex).
*
* Errors are reported through a caller-provided cf_error_t out
* parameter — never through stderr or thread-local globals. Free
* any populated cf_error_t with cf_error_free().
*
* Every output struct has a matching _free() that releases its
* heap-allocated members. Stack-allocate the struct, pass its
* address in, free it when done.
*/
#ifndef CLAWDFORGE_H
#define CLAWDFORGE_H
#include <stddef.h>
#ifdef __cplusplus
extern "C" {
#endif
/* Visibility / export attribute. The shared library is built with
* -fvisibility=hidden by default; CF_API marks the public surface so
* those symbols stay visible. The static library and consumers use
* the empty default. */
#if defined(_WIN32) || defined(__CYGWIN__)
# if defined(CLAWDFORGE_BUILDING_DLL)
# define CF_API __declspec(dllexport)
# elif defined(CLAWDFORGE_USING_DLL)
# define CF_API __declspec(dllimport)
# else
# define CF_API
# endif
#else
# if defined(CLAWDFORGE_BUILDING_LIB) && defined(__GNUC__)
# define CF_API __attribute__((visibility("default")))
# else
# define CF_API
# endif
#endif
/* ------------------------------------------------------------------ */
/* Versioning */
/* ------------------------------------------------------------------ */
#define CLAWDFORGE_VERSION_MAJOR 0
#define CLAWDFORGE_VERSION_MINOR 1
#define CLAWDFORGE_VERSION_PATCH 0
#define CLAWDFORGE_VERSION_STRING "0.1.0"
/* Maximum HTTP response body size accepted by the SDK. A response
* larger than this aborts mid-transfer with CF_ERR_TRANSPORT, which
* caps the heap a malicious or runaway server can force the client
* to allocate. 64 MiB is comfortably larger than any expected
* /run, /healthz, or /admin response. */
#define CF_MAX_RESPONSE_BYTES ((size_t)64 * 1024 * 1024)
/* Returns the runtime library version string ("X.Y.Z"). */
CF_API const char *cf_version(void);
/* ------------------------------------------------------------------ */
/* Status codes */
/* ------------------------------------------------------------------ */
typedef enum cf_status {
CF_OK = 0, /* success */
CF_ERR_AUTH = 1, /* 401 / 403 from server, or missing token */
CF_ERR_API = 2, /* server returned a structured error envelope */
CF_ERR_TRANSPORT = 3, /* network / TLS / connection */
CF_ERR_USAGE = 4, /* caller passed a bad argument */
CF_ERR_OOM = 5, /* malloc / calloc returned NULL */
CF_ERR_PARSE = 6 /* server response was not the expected JSON shape */
} cf_status_t;
/* ------------------------------------------------------------------ */
/* Error type */
/* ------------------------------------------------------------------ */
/*
* cf_error_t is filled in by every fallible function on failure.
* On CF_OK the contents are left untouched — do not call cf_error_free
* if the call returned CF_OK.
*
* Recommended pattern:
*
* cf_error_t err = {0};
* if (cf_run(c, &req, &res, &err) != CF_OK) {
* fprintf(stderr, "%s\n", cf_error_message(&err));
* cf_error_free(&err);
* return 1;
* }
*/
typedef struct cf_error {
cf_status_t code;
long http_status; /* HTTP status code if applicable, else 0 */
char *message; /* heap-allocated, NUL-terminated */
} cf_error_t;
CF_API const char *cf_error_message(const cf_error_t *err);
CF_API void cf_error_free(cf_error_t *err);
/* Static, never-NULL human label for a status code (e.g. "CF_OK"). */
CF_API const char *cf_status_str(cf_status_t code);
/* ------------------------------------------------------------------ */
/* Client */
/* ------------------------------------------------------------------ */
/* Opaque. */
typedef struct cf_client cf_client_t;
/*
* Construct a new client.
*
* base_url: e.g. "http://192.168.0.5:8800". A trailing slash is
* tolerated. Required.
* token: bearer token for /run + /files. May be NULL if the
* caller only intends to use admin endpoints with a
* separately-provided admin token (see cf_client_set_admin_token).
*
* Returns NULL on allocation failure. cf_client_free() releases.
*/
CF_API cf_client_t *cf_client_new(const char *base_url, const char *token);
/* Optional: install or replace the admin bootstrap token used for
* the /admin endpoints. Pass NULL to clear. */
CF_API cf_status_t cf_client_set_admin_token(cf_client_t *c, const char *admin_token);
/* Optional: set the libcurl connection + request timeout in seconds.
* Default is 600 seconds. Setting <= 0 leaves the current value. */
CF_API void cf_client_set_timeout_secs(cf_client_t *c, long timeout_secs);
CF_API void cf_client_free(cf_client_t *c);
/* ------------------------------------------------------------------ */
/* /healthz */
/* ------------------------------------------------------------------ */
typedef struct cf_healthz {
int ok; /* "ok" field */
int claude_present; /* "claude_present" field */
char *claude_version; /* "claude_version" or NULL */
} cf_healthz_t;
CF_API cf_status_t cf_healthz(cf_client_t *c, cf_healthz_t *out, cf_error_t *err);
CF_API void cf_healthz_free(cf_healthz_t *h);
/* ------------------------------------------------------------------ */
/* /run */
/* ------------------------------------------------------------------ */
/*
* Request struct. Initialise with `cf_run_request_t r = {0};` and
* populate the fields you need. Strings are caller-owned; clawdforge
* copies them as needed.
*/
typedef struct cf_run_request {
const char *prompt; /* required, non-empty */
const char *model; /* optional, NULL = server default */
const char *system; /* optional system prompt */
const char *const *files; /* array of file_token strings */
size_t files_count;
int timeout_secs; /* 0 = server default; else 5..600 */
} cf_run_request_t;
/*
* Response from a successful /run call.
*
* result_json: the inner "result" field re-serialised back to a
* JSON string. Always non-NULL on CF_OK. If the server
* returned a string, this is a JSON-encoded string
* (including the surrounding quotes); if it returned
* an object, this is the object as JSON.
*
* result_is_string: 1 iff the server's "result" was a JSON string;
* 0 if it was an object/array/number/bool/null.
*
* stop_reason: e.g. "end_turn"; may be NULL.
*
* duration_ms: server-reported duration in ms.
*/
typedef struct cf_run_result {
char *result_json;
int result_is_string;
char *stop_reason;
long duration_ms;
} cf_run_result_t;
CF_API cf_status_t cf_run(cf_client_t *c,
const cf_run_request_t *req,
cf_run_result_t *out,
cf_error_t *err);
CF_API void cf_run_result_free(cf_run_result_t *r);
/*
* Convenience: parse out->result_json with cJSON. Returns NULL if
* the result was not valid JSON (shouldn't happen in normal use,
* but defensive). The caller must cJSON_Delete() the returned node.
*
* The return type is `void *` so the public header does not have
* to expose the cJSON struct. Callers including cJSON.h can cast
* directly to `cJSON *`.
*/
CF_API void *cf_run_result_as_cjson(const cf_run_result_t *r);
/* ------------------------------------------------------------------ */
/* /files */
/* ------------------------------------------------------------------ */
typedef struct cf_file_token {
char *file_token; /* "ff_..." */
long ttl_secs;
long size;
} cf_file_token_t;
/*
* Upload a file from disk via multipart/form-data. The file is
* streamed (not buffered into memory).
*
* path: absolute or relative filesystem path; must be readable.
* ttl_secs: 60..86400; 0 selects the server default (3600).
*/
CF_API cf_status_t cf_upload_file(cf_client_t *c,
const char *path,
long ttl_secs,
cf_file_token_t *out,
cf_error_t *err);
CF_API void cf_file_token_free(cf_file_token_t *ft);
/* ------------------------------------------------------------------ */
/* /admin/tokens */
/* ------------------------------------------------------------------ */
typedef struct cf_admin_token {
char *name;
char *token; /* plaintext, only present on create */
char **ip_cidrs;
size_t ip_cidrs_count;
} cf_admin_token_t;
typedef struct cf_admin_token_info {
char *name;
char **ip_cidrs;
size_t ip_cidrs_count;
long created_at; /* UNIX seconds, 0 if absent */
long last_used_at; /* UNIX seconds, 0 if absent */
} cf_admin_token_info_t;
typedef struct cf_admin_token_list {
cf_admin_token_info_t *items;
size_t count;
} cf_admin_token_list_t;
/* Mint a new app token. ip_cidrs/ip_cidrs_count may be 0 to omit. */
CF_API cf_status_t cf_admin_create_token(cf_client_t *c,
const char *name,
const char *const *ip_cidrs,
size_t ip_cidrs_count,
cf_admin_token_t *out,
cf_error_t *err);
CF_API void cf_admin_token_free(cf_admin_token_t *t);
CF_API cf_status_t cf_admin_list_tokens(cf_client_t *c,
cf_admin_token_list_t *out,
cf_error_t *err);
CF_API void cf_admin_token_list_free(cf_admin_token_list_t *l);
CF_API cf_status_t cf_admin_revoke_token(cf_client_t *c,
const char *name,
cf_error_t *err);
#ifdef __cplusplus
} /* extern "C" */
#endif
#endif /* CLAWDFORGE_H */
Reference in a new issue View git blame Copy permalink