Squashed commit of the following:

commit a639280
Author: vnugent <public@vaughnnugent.com>
Date:   Mon Aug 12 13:56:03 2024 -0400

    simple cleanup & some api notes

commit a970126
Merge: ec7461d fb3608b
Author: vnugent <public@vaughnnugent.com>
Date:   Wed Aug 7 21:39:28 2024 -0400

    Merge branch 'master' into develop

CMakeLists.txt

@@ -421,9 +421,20 @@ install(TARGETS ${_NC_PROJ_NAME}_static
     INCLUDES DESTINATION include
 )
 
-install(FILES 
-	include/noscrypt.h
+SET(NC_INSTALL_HEADERS 
+	include/noscrypt.h	#static install headers
 	include/platform.h
+)
+
+if(NC_ENABLE_UTILS)
+	LIST(APPEND 
+		NC_INSTALL_HEADERS
+		include/noscryptutil.h
+	)
+endif()
+
+install(FILES 
+	${NC_INSTALL_HEADERS}
 	DESTINATION noscrypt
 )
 

include/noscrypt.h

@@ -125,6 +125,27 @@ extern "C" {
 #define NC_ENC_SET_NIP44_MAC_KEY	0x03
 #define NC_ENC_SET_NIP04_KEY		0x04
 
+/*
+* API NOTES:
+* 
+* - Decisions on integer width
+*   Since noscrypt will target general purpose processors and embedded 
+*   systems (future) I didn't want to risk word size issues causing under/overflow
+*   for the time being, so a fixed integer width was used and internal code
+*   supports and guards against the platform default integer width (size_t)
+* 
+*   I'd like to support 64bit stuff, but really the underlying systems don't 
+*   need to support that size buffer, nor do I expect platforms to have more than
+*   4GB sized buffers (int32_t), it's just not practial and most work is on 
+*   digests anyway. 
+* 
+* - Decisions on unsigned vs signed
+*   Yeah, I know this is a popular squabble in C land, but implementation details
+*   should not trouble the user. If I expect an unsigned int, then it should be 
+*   explicit, negative number guards are cumbersom to handle return codes with
+*   that IMO most engineers don't bother doing anyway or doing well at the very
+*   least, so I'm using unsgined integers. Sorry, not sorry.
+*/
 
 /* A compressed resul/return value, negative values 
 are failure, 0 is success and positive values are 

src/nc-util.h

@@ -193,13 +193,10 @@ static _nc_fn_inline void ncSpanWrite(span_t span, uint32_t offset, const uint8_
 
 static _nc_fn_inline void ncSpanAppend(span_t span, uint32_t* offset, const uint8_t* data, uint32_t size)
 {
-	DEBUG_ASSERT2(ncSpanIsValid(span),	"Expected span to be non-null")
 	DEBUG_ASSERT2(offset != NULL,		"Expected offset to be non-null")
-	DEBUG_ASSERT2(data != NULL,			"Expected data to be non-null")
-	DEBUG_ASSERT2(*offset + size <= span.size, "Expected offset + size to be less than span size")
 
-	/* Copy data to span */
-	MEMMOV(span.data + *offset, data, size);
+	/* Copy data to span (also performs argument assertions) */
+	ncSpanWrite(span, *offset, data, size);
 
 	/* Increment offset */
 	*offset += size;
@@ -213,7 +210,11 @@ static _nc_fn_inline span_t ncSpanSlice(span_t span, uint32_t offset, uint32_t s
 	DEBUG_ASSERT2(offset + size <= span.size, "Expected offset + size to be less than span size")
 
 	/* Initialize slice, offset input data by the specified offset */
-	ncSpanInit(&slice, span.data + offset, size);
+	ncSpanInit(
+		&slice, 
+		ncSpanGetOffset(span, offset), 
+		size
+	);
 
 	return slice;
 }
@@ -226,7 +227,11 @@ static _nc_fn_inline cspan_t ncSpanSliceC(cspan_t span, uint32_t offset, uint32_
 	DEBUG_ASSERT2(offset + size <= span.size, "Expected offset + size to be less than span size")
 
 	/* Initialize slice, offset input data by the specified offset */
-	ncSpanInitC(&slice, span.data + offset, size);
+	ncSpanInitC(
+		&slice, 
+		ncSpanGetOffsetC(span, offset), 
+		size
+	);
 
 	return slice;
 }