gln_plugin_approve_binary

Declared in <galanthus/c_api/gln_capi.h>.

GLN_API gln_status_t GLN_CALL gln_plugin_approve_binary(
    const gln_plugin_approval_request_t* in_request,
    char**                               out_approval_json,
    gln_error_t*                         out_error);

Family: Plugin trust functions
Return type: gln_status_t

Purpose

Validates a plugin bundle and records an explicit trust pin in the plugin pin store.

Use this function from library or operator tooling that needs to approve a plugin binary after presenting or checking its trust digests.

Return

Returns GLN_OK on success and a non-OK gln_status_t value on failure.

Type	Nullability	Ownership
`gln_status_t`	value	value

Parameters

Name	Direction	Type	Nullability	Ownership
`in_request`	input	`const gln_plugin_approval_request_t*`	nonnull	borrowed
`out_approval_json`	output	`char**`	nonnull	transferred_out
`out_error`	output	`gln_error_t*`	nullable	caller_allocated_output

Approval Request

in_request must point to a gln_plugin_approval_request_t initialized by calling gln_default_plugin_approval_request and filled with a non-empty plugin_binary_path.

The manifest path is derived from the binary path by replacing the binary extension with .manifest.json.

The optional expected digest fields are compared after staging and dependency validation and before the pin store is written. A mismatch returns GLN_ERR_PLUGIN_NOT_TRUSTED with issue type plugin_digest_mismatch.

Trust Validation

Approval stages the binary and manifest through the same trust path used for plugin loading, rejects undeclared native sidecar libraries, and verifies native dependencies against the host allowlist.

A rejected dependency returns GLN_ERR_PLUGIN_NOT_TRUSTED with the plugin trust issue type reported by the validator. The pin store is not modified on validation failure.

Result JSON

On success, out_approval_json receives a caller-owned JSON report with manifest, binary, and pin_store objects.

manifest contains plugin identity and capability fields from the manifest. binary contains the resolved binary path, manifest path, bundle digest, manifest digest, binary digest, and dependency digest. pin_store contains the pin-store path, approval timestamp, and whether an existing pin was replaced.

Release the returned JSON string with gln_release_string.

Pin Store

Pin-store write failures return a non-OK status and issue type plugin_pin_store_write_failed.

The library never approves a plugin implicitly during load; callers must invoke this approval operation before a plugin with matching manifest and binary digests can load successfully.