--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/auth/auth_crypto.h	Fri Aug 07 07:34:12 2026 -0700
@@ -0,0 +1,106 @@
+#ifndef ZENBU_AUTH_CRYPTO_H
+#define ZENBU_AUTH_CRYPTO_H
+
+#include "dowa/dowa.h"
+
+#define AUTH_CRYPTO_PASSWORD_MAX_BYTES 1024
+#define AUTH_CRYPTO_PASSWORD_SALT_BYTES 16
+#define AUTH_CRYPTO_PASSWORD_HASH_BYTES 32
+#define AUTH_CRYPTO_PASSWORD_HASH_ENCODED_SIZE 160
+
+#define AUTH_CRYPTO_TOKEN_BYTES 32
+#define AUTH_CRYPTO_TOKEN_SIZE 44
+#define AUTH_CRYPTO_TOKEN_DIGEST_BYTES 32
+#define AUTH_CRYPTO_TOKEN_DIGEST_SIZE 65
+
+#define AUTH_CRYPTO_COOKIE_SECRET_MIN_BYTES 32
+#define AUTH_CRYPTO_COOKIE_SECRET_MAX_BYTES 1024
+#define AUTH_CRYPTO_IP_MAX_BYTES 128
+#define AUTH_CRYPTO_IP_BINDING_DIGEST_SIZE 65
+#define AUTH_CRYPTO_GUEST_UUID_SIZE 37
+#define AUTH_CRYPTO_GUEST_COOKIE_SIZE 256
+
+typedef enum {
+  AUTH_CRYPTO_OK = 0,
+  AUTH_CRYPTO_INVALID_ARGUMENT = 1,
+  AUTH_CRYPTO_BUFFER_TOO_SMALL = 2,
+  AUTH_CRYPTO_PASSWORD_TOO_LONG = 3,
+  AUTH_CRYPTO_RANDOM_FAILED = 4,
+  AUTH_CRYPTO_OPERATION_FAILED = 5,
+  AUTH_CRYPTO_MALFORMED = 6,
+  AUTH_CRYPTO_AUTHENTICATION_FAILED = 7,
+  AUTH_CRYPTO_EXPIRED = 8,
+  AUTH_CRYPTO_IP_MISMATCH = 9,
+} Auth_Crypto_Result;
+
+typedef struct {
+  char guest_uuid[AUTH_CRYPTO_GUEST_UUID_SIZE];
+  uint64 expiration_unix;
+} Auth_Crypto_Guest_Cookie;
+
+Auth_Crypto_Result Auth_Crypto_Password_Hash(
+    const char *password,
+    char *encoded_hash,
+    size_t encoded_hash_capacity);
+
+Auth_Crypto_Result Auth_Crypto_Password_Verify(
+    const char *password,
+    const char *encoded_hash);
+
+Auth_Crypto_Result Auth_Crypto_Token_Generate(
+    char *token,
+    size_t token_capacity);
+
+Auth_Crypto_Result Auth_Crypto_Token_Digest(
+    const char *token,
+    char *digest_hex,
+    size_t digest_hex_capacity);
+
+Auth_Crypto_Result Auth_Crypto_IP_Binding_Digest(
+    const uint8 *cookie_secret,
+    size_t cookie_secret_length,
+    const char *canonical_peer_ip,
+    char *digest_hex,
+    size_t digest_hex_capacity);
+
+Auth_Crypto_Result Auth_Crypto_Guest_Cookie_Create(
+    const uint8 *cookie_secret,
+    size_t cookie_secret_length,
+    const char *guest_uuid,
+    uint64 expiration_unix,
+    const char *ip_binding_digest,
+    char *cookie,
+    size_t cookie_capacity);
+
+Auth_Crypto_Result Auth_Crypto_Guest_Cookie_Verify(
+    const uint8 *cookie_secret,
+    size_t cookie_secret_length,
+    const char *cookie,
+    uint64 current_unix,
+    const char *expected_ip_binding_digest,
+    Auth_Crypto_Guest_Cookie *guest_cookie);
+
+const char *Auth_Crypto_Result_String(Auth_Crypto_Result result);
+
+/*
+ * Validate an encoded password hash string without running scrypt.
+ * Checks exact format, version string, parameters (N/r/p), hex salt length,
+ * hex hash length, and that all hex characters are valid.
+ * Returns AUTH_CRYPTO_OK if well-formed, AUTH_CRYPTO_MALFORMED otherwise.
+ * Does NOT verify against a password; use Auth_Crypto_Password_Verify for that.
+ */
+Auth_Crypto_Result Auth_Crypto_Password_Hash_Validate(const char *encoded_hash);
+
+/*
+ * Encode byte_count bytes from bytes as unpadded base64url into out.
+ * out_capacity must be at least ((byte_count + 2) / 3 * 4) - padding + 1;
+ * for AUTH_CRYPTO_TOKEN_BYTES (32) bytes that is AUTH_CRYPTO_TOKEN_SIZE (44).
+ * Returns number of characters written (without NUL), or 0 on error.
+ */
+size_t Auth_Crypto_Base64url_Encode(
+    const uint8 *bytes,
+    size_t       byte_count,
+    char        *out,
+    size_t       out_capacity);
+
+#endif