inbox: add health endpoint && docs

Author: 01zulfi

Notesnook.Inbox.API/README.md

@@ -0,0 +1,33 @@
+# Notesnook Inbox API
+
+## Running locally
+
+### Requirements
+
+- Bun (v1.0.0 or higher) 
+
+### Environment variables
+
+- `PORT`
+- `NOTESNOOK_API_SERVER_URL`
+
+### Commands
+
+- `bun install` - Install dependencies
+- `bun run dev` - Start the development server
+- `bun run build` - Build the project for production
+- `bun run start` - Start the production server
+
+## Self-hosting
+
+...
+
+## Writing from scratch
+
+The inbox API server is pretty simple to write from scratch in any programming language and/or framework. There's only one endpoint that needs to be implemented, which does these three steps:
+
+1. Fetch the user's public inbox API key from the Notesnook API.
+2. Encrypt the payload (via libsodium).
+3. Post the encrypted payload to the Notesnook API. 
+
+You can refer to the [source code](./src/index.ts) for implementation details.

Notesnook.Inbox.API/src/index.ts

@@ -9,6 +9,7 @@ if (!NOTESNOOK_API_SERVER_URL) {
 }
 
 let sodium: typeof _sodium;
+let isReady = false;
 
 const RawInboxItemSchema = z.object({
   title: z.string().min(1, "Title is required"),
@@ -39,6 +40,20 @@ interface EncryptedInboxItem {
   salt: string;
 }
 
+/**
+ * Encrypts raw data using a hybrid encryption scheme combining symmetric and asymmetric cryptography.
+ *
+ * The encryption process follows these steps:
+ * - Generate a random symmetric password using XChaCha20-Poly1305-IETF key generation
+ * - Generate a random salt for key derivation
+ * - Derive an encryption key from the password using Argon2i13
+ * - Generate a random nonce (IV) for the symmetric encryption
+ * - Encrypt the data using XChaCha20-Poly1305-IETF with the derived key
+ * - Encrypt the derived key using the recipient's public key (X25519 sealed box)
+ *
+ * @param {string} rawData - The plaintext data to encrypt
+ * @param {string} publicKey - The recipient's X25519 public key encoded in base64 URL-safe format without padding.
+ */
 function encrypt(rawData: string, publicKey: string): EncryptedInboxItem {
   try {
     const password = sodium.crypto_aead_xchacha20poly1305_ietf_keygen();
@@ -133,6 +148,12 @@ app.use(
     limit: 60,
   })
 );
+app.get("/health", (_, res) => {
+  if (!isReady) {
+    return res.status(503).json({ status: "unavailable" });
+  }
+  return res.status(200).json({ status: "ok" });
+});
 app.post("/inbox", async (req, res) => {
   try {
     const apiKey = req.headers["authorization"];
@@ -184,6 +205,7 @@ app.post("/inbox", async (req, res) => {
 
   const PORT = Number(process.env.PORT || "5181");
   app.listen(PORT, () => {
+    isReady = true;
     console.log(`📫 notesnook inbox api server running on port ${PORT}`);
   });
 })();