Why not use forward declarations without public definitions to create opaque types? For example, in the public header file:

typedef struct handle handle_t;

Then, only in the code which needs to access the concrete type:

struct handle {
   ...
};

Then the compiler can correctly allow a handle_t * only where the function signature wants one.

I also wrote about a similar technique in D

In the Rust community this is known as the “newtype” pattern.

This is a neat trick!