09_Cryptography.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "8833df6d-4615-4937-a43a-5dabef7a72d1",
   "metadata": {},
   "source": [
    "## Hashing\n",
    "\n",
    "Hashing data is a common operation that is facilitated\n",
    "through Deno's support for the Web Crypto API. In addition,\n",
    "the Deno standard library's implementation extends the standard API, allowing for\n",
    "more advanced uses.\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "409ba301-8b29-45bd-9dcc-cf40ca6bb94e",
   "metadata": {},
   "source": [
    "In our first example, we'll hash the contents of a string variable.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "id": "2ca85e33-8271-41e6-ae7d-c13432587869",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "\u001b[32m\"The easiest, most secure JavaScript runtime.\"\u001b[39m"
      ]
     },
     "execution_count": 1,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "const message = \"The easiest, most secure JavaScript runtime.\";\n",
    "message;\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e970d7af-9fc9-4f34-9a61-09319a145b2b",
   "metadata": {},
   "source": [
    "Before we can pass our message to the hashing function, we first need to encode it into a uint8 array.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "id": "900e18bf-9474-423e-8efc-fd6e9d149644",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "Uint8Array(44) [\n",
       "   \u001b[33m84\u001b[39m, \u001b[33m104\u001b[39m, \u001b[33m101\u001b[39m,  \u001b[33m32\u001b[39m, \u001b[33m101\u001b[39m,  \u001b[33m97\u001b[39m, \u001b[33m115\u001b[39m, \u001b[33m105\u001b[39m, \u001b[33m101\u001b[39m,\n",
       "  \u001b[33m115\u001b[39m, \u001b[33m116\u001b[39m,  \u001b[33m44\u001b[39m,  \u001b[33m32\u001b[39m, \u001b[33m109\u001b[39m, \u001b[33m111\u001b[39m, \u001b[33m115\u001b[39m, \u001b[33m116\u001b[39m,  \u001b[33m32\u001b[39m,\n",
       "  \u001b[33m115\u001b[39m, \u001b[33m101\u001b[39m,  \u001b[33m99\u001b[39m, \u001b[33m117\u001b[39m, \u001b[33m114\u001b[39m, \u001b[33m101\u001b[39m,  \u001b[33m32\u001b[39m,  \u001b[33m74\u001b[39m,  \u001b[33m97\u001b[39m,\n",
       "  \u001b[33m118\u001b[39m,  \u001b[33m97\u001b[39m,  \u001b[33m83\u001b[39m,  \u001b[33m99\u001b[39m, \u001b[33m114\u001b[39m, \u001b[33m105\u001b[39m, \u001b[33m112\u001b[39m, \u001b[33m116\u001b[39m,  \u001b[33m32\u001b[39m,\n",
       "  \u001b[33m114\u001b[39m, \u001b[33m117\u001b[39m, \u001b[33m110\u001b[39m, \u001b[33m116\u001b[39m, \u001b[33m105\u001b[39m, \u001b[33m109\u001b[39m, \u001b[33m101\u001b[39m,  \u001b[33m46\u001b[39m\n",
       "]"
      ]
     },
     "execution_count": 2,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "const messageBuffer = new TextEncoder().encode(message);\n",
    "messageBuffer;\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "1483ec71-4060-4bc4-bccf-4f1b00d70043",
   "metadata": {},
   "source": [
    "Here, we use the built-in `crypto.subtle.digest` method to hash our original message.\n",
    "The hash is returned as an `ArrayBuffer`. To obtain a string\n",
    "we'll need to do a little more work.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "id": "26ea0e8e-2adb-467c-9ebc-13e6c102691e",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "ArrayBuffer {\n",
       "  \u001b[36m[Uint8Contents]\u001b[39m: <1a c7 d6 a8 8e 74 e6 3d 1e 2c 28 70 fa 6e 80 8c 4e d6 b4 27 27 70 bf c2 2c a1 bb a7 e1 16 79 20>,\n",
       "  byteLength: \u001b[33m32\u001b[39m\n",
       "}"
      ]
     },
     "execution_count": 3,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "const hashBuffer = await crypto.subtle.digest(\"SHA-256\", messageBuffer);\n",
    "hashBuffer;\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "66b09373-7f99-4431-ae02-734e0d585faf",
   "metadata": {},
   "source": [
    "We can decode this into a string using the standard\n",
    "library's `toHashString` method.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "id": "ab8d29de-6028-441f-b79f-bde12ec1770f",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "1ac7d6a88e74e63d1e2c2870fa6e808c4ed6b4272770bfc22ca1bba7e1167920\n"
     ]
    }
   ],
   "source": [
    "import { toHashString } from \"https://deno.land/std@0.194.0/crypto/to_hash_string.ts\";\n",
    "const hash = toHashString(hashBuffer);\n",
    "console.log(hash);\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f31f72f2-15c1-42f5-979b-200a8d5d4b60",
   "metadata": {},
   "source": [
    "For our second example, we'll hash the contents of a file.\n",
    "Hashing a file is a common operation and doing this\n",
    "without loading the whole file into memory is a typical\n",
    "requirement.\n",
    "\n",
    "The standard library has extensions to the Web\n",
    "Crypto API that are useful when doing things\n",
    "like hashing a file. These can be accessed through the\n",
    "`crypto` module, a drop-in replacement for the Web Crypto\n",
    "API that delegates to the native implementation when\n",
    "possible.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "id": "e162d5b3-b5fd-41ed-a164-9a8e491bc402",
   "metadata": {},
   "outputs": [],
   "source": [
    "import { crypto } from \"jsr:@std/crypto\";\n",
    "const file = await Deno.open(\"09_Cryptography.ipynb\", { read: true });"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "1c04a2f5-381e-4e86-8ad6-1239f477eafb",
   "metadata": {},
   "source": [
    "We obtain an async iterable using the readable property.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "id": "859dd71e-69ac-478a-959b-44753ce3d71a",
   "metadata": {},
   "outputs": [],
   "source": [
    "const readableStream = file.readable;\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a7091aeb-fd59-4a5e-a5d4-4c5b7ff5ab43",
   "metadata": {},
   "source": [
    "This time, when we call `crypto.subtle.digest`, we're using the\n",
    "imported version that allows us to operate on the\n",
    "async iterable.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "id": "8f55f269-e109-4055-9db7-2c50b73710b0",
   "metadata": {},
   "outputs": [],
   "source": [
    "const fileHashBuffer = await crypto.subtle.digest(\"SHA-256\", readableStream);\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "fe96a152-5765-45bb-b87e-dedba027ac00",
   "metadata": {},
   "source": [
    "Finally, we obtain the hex result using toHashString like earlier.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "id": "87de4520-e231-464b-93a3-f05709f04052",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "d5f47b35c2b63fe0c066a3acbc37f460c64e0338fb7081c4ef9e7e09a8300aba\n"
     ]
    }
   ],
   "source": [
    "const fileHash = toHashString(fileHashBuffer);\n",
    "console.log(fileHash);\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "456bb2f4",
   "metadata": {},
   "source": [
    "## Generating & Validating UUIDs\n",
    "\n",
    "UUIDs (universally unique identifier) can be used to uniquely identify some object or data.\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "6453f192",
   "metadata": {},
   "source": [
    "A random UUID can be generated using the builtin Web Cryptography API. This type of UUID is also known as UUID v4.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "id": "aa1703d2",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "\u001b[32m\"42629b95-a84c-4339-b404-80a05c17e5b1\"\u001b[39m"
      ]
     },
     "execution_count": 9,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "const myUUID = crypto.randomUUID();\n",
    "myUUID;\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f39a6f76",
   "metadata": {},
   "source": [
    "The standard library contains some more functions for working with UUIDs.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "id": "ba3a1035",
   "metadata": {},
   "outputs": [],
   "source": [
    "import * as uuid from \"jsr:@std/uuid\";\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ef75055b",
   "metadata": {},
   "source": [
    "You can validate that a given string is a valid UUID.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "id": "4ab03528",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "\u001b[33mfalse\u001b[39m"
      ]
     },
     "execution_count": 11,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "uuid.validate(\"not a UUID\");\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "id": "4168a936",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "\u001b[33mtrue\u001b[39m"
      ]
     },
     "execution_count": 12,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "uuid.validate(\"6ec0bd7f-11c0-43da-975e-2a8ad9ebae0b\");\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f88a94f6",
   "metadata": {},
   "source": [
    "You can also generate a time-based (v1) UUID. By default this uses system time as the time source.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "id": "cd7b2e2e",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "\u001b[32m\"5fe4e420-1475-11ef-ae98-c303dc00e183\"\u001b[39m"
      ]
     },
     "execution_count": 13,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "uuid.v1.generate();\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "0917baad",
   "metadata": {},
   "source": [
    "SHA-1 namespaced (v5) UUIDs can also be generated. For this you need to specify a namespace and data:\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "id": "8f1746be",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "\u001b[32m\"21bbd59d-9801-53ce-8902-9559de3ebd39\"\u001b[39m"
      ]
     },
     "execution_count": 14,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "const NAMESPACE_URL = \"6ba7b810-9dad-11d1-80b4-00c04fd430c8\";\n",
    "\n",
    "const data = new TextEncoder().encode(\"deno.land\");\n",
    "await uuid.v5.generate(NAMESPACE_URL, data);\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "514fcdd5",
   "metadata": {},
   "source": [
    "## ULID\n",
    "\n",
    "One common need for distributed systems are identifiers. ULIDs are a universally unique lexicographically sortable identifier with some nice properties. They are 128-bit values, encoded as 26 character strings which also encode the timestamp. They play very nicely with Deno KV.\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "8dd3ee0a",
   "metadata": {},
   "source": [
    "The standard library contains a function for generating ULIDs.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "id": "b7533f52",
   "metadata": {},
   "outputs": [],
   "source": [
    "import { ulid } from \"jsr:@std/ulid\";\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "5527d5aa",
   "metadata": {},
   "source": [
    "To generate a ULID, simply call the function.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 16,
   "id": "50b9c679",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "\u001b[32m\"01HY3TJYVX62VNYRCYGTBYB55M\"\u001b[39m"
      ]
     },
     "execution_count": 16,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "ulid();\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "28bc9d96",
   "metadata": {},
   "source": [
    "ULIDs can also be generated from a timestamp. This is useful for migrating from another system.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 17,
   "id": "d5850f73",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "\u001b[32m\"01HY3TJYW6XXPDX38SCQFMT9RA\"\u001b[39m"
      ]
     },
     "execution_count": 17,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "const timestamp = Date.now();\n",
    "ulid(timestamp);\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "bb9a4da9",
   "metadata": {},
   "source": [
    "Given a ULID, you can get the timestamp back out\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 18,
   "id": "82d82f5c",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "\u001b[33m1715967982479\u001b[39m"
      ]
     },
     "execution_count": 18,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "import { decodeTime } from \"jsr:@std/ulid\";\n",
    "const myULID = ulid();\n",
    "decodeTime(myULID);"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "2bea4843",
   "metadata": {},
   "source": [
    "Optionally, if you're not on a distributed system and want monotonic ULIDs, you can use the monotonic ULID generator instead.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 19,
   "id": "c81701db",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "01HY3TJYWQ2VZJXSVE3EC4VD0F\n",
      "01HY3TJYWQ2VZJXSVE3EC4VD0G\n",
      "01HY3TJYWQ2VZJXSVE3EC4VD0H\n"
     ]
    }
   ],
   "source": [
    "import { monotonicUlid } from \"jsr:@std/ulid\";\n",
    "\n",
    "for (let i = 0; i < 3; i++) {\n",
    "  console.log(monotonicUlid());\n",
    "}\n"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Deno",
   "language": "typescript",
   "name": "deno"
  },
  "language_info": {
   "codemirror_mode": "typescript",
   "file_extension": ".ts",
   "mimetype": "text/x.typescript",
   "name": "typescript",
   "nbconvert_exporter": "script",
   "pygments_lexer": "typescript",
   "version": "5.4.5"
  },
  "widgets": {
   "application/vnd.jupyter.widget-state+json": {
    "state": {},
    "version_major": 2,
    "version_minor": 0
   }
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}