{"id":51578788,"url":"https://github.com/systemslibrarian/crypto-lab-oram-vault","last_synced_at":"2026-07-11T03:32:25.825Z","repository":{"id":367059523,"uuid":"1215058617","full_name":"systemslibrarian/crypto-lab-oram-vault","owner":"systemslibrarian","description":"Browser-based Path ORAM demo implementing Stefanov et al. (CCS 2013 / JACM 2018). Hides access patterns from cloud storage: tree, stash, position map, and adversary-view visualization.","archived":false,"fork":false,"pushed_at":"2026-06-24T10:33:03.000Z","size":57,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-24T12:15:32.548Z","etag":null,"topics":["access-pattern-hiding","aes-gcm","cloud-storage-security","crypto-lab","cryptography","encrypted-storage","goldreich-ostrovsky","oblivious-ram","oram","path-oram","privacy-preserving","secure-computation","side-channel-protection"],"latest_commit_sha":null,"homepage":"https://systemslibrarian.github.io/crypto-lab-oram-vault/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/systemslibrarian.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-19T12:28:45.000Z","updated_at":"2026-06-24T10:33:06.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/systemslibrarian/crypto-lab-oram-vault","commit_stats":null,"previous_names":["systemslibrarian/crypto-lab-oram-vault"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/systemslibrarian/crypto-lab-oram-vault","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/systemslibrarian%2Fcrypto-lab-oram-vault","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/systemslibrarian%2Fcrypto-lab-oram-vault/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/systemslibrarian%2Fcrypto-lab-oram-vault/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/systemslibrarian%2Fcrypto-lab-oram-vault/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/systemslibrarian","download_url":"https://codeload.github.com/systemslibrarian/crypto-lab-oram-vault/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/systemslibrarian%2Fcrypto-lab-oram-vault/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35350133,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-11T02:00:05.354Z","response_time":104,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["access-pattern-hiding","aes-gcm","cloud-storage-security","crypto-lab","cryptography","encrypted-storage","goldreich-ostrovsky","oblivious-ram","oram","path-oram","privacy-preserving","secure-computation","side-channel-protection"],"created_at":"2026-07-11T03:32:25.723Z","updated_at":"2026-07-11T03:32:25.817Z","avatar_url":"https://github.com/systemslibrarian.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# crypto-lab-oram-vault\n\n## What It Is\n\n**Browser-based Path ORAM demo** implementing the protocol from Stefanov et al. \"Path ORAM: An Extremely Simple Oblivious RAM Protocol\" (CCS 2013, JACM 2018).\n\nA fully interactive browser demo of Path ORAM — the Oblivious RAM construction that hides *access patterns* from cloud storage providers. Encryption hides the contents of your data; ORAM hides which locations you access. Path ORAM is the protocol used in Intel SGX-based secure processors, FPGA secure designs, ZeroTrace, Obliviate, and privacy-preserving cloud database systems.\n\nThe demo uses a module-boundary-enforced client/server separation: the \"server\" module stores only encrypted blobs and responds to path read/write requests — it literally cannot see block IDs, the position map, or stash contents. All encryption uses AES-256-GCM via the Web Crypto API. Randomness exclusively via `crypto.getRandomValues` — never `Math.random()`.\n\n**Parameters:** N=16 blocks, Z=4 bucket size, L=4 tree height, 32-byte blocks, 12-byte GCM nonces.\n\n## When to Use It\n\n- Understanding why encryption hides contents but not access patterns\n- Teaching the Goldreich–Ostrovsky logarithmic overhead theorem (1987/1996)\n- Evaluating ORAM for healthcare record systems, SGX enclaves, cloud storage\n- Visualizing how the Path ORAM tree + stash + position map work together\n- Comparing ORAM cost vs. alternatives (PIR, TEE, differential privacy)\n- Do NOT use for production — use a maintained library (PathORAM C++, Go equivalents); this is educational and runs in a browser.\n\n## Live Demo\n\n**[systemslibrarian.github.io/crypto-lab-oram-vault](https://systemslibrarian.github.io/crypto-lab-oram-vault/)**\n\nThe demo presents five exhibits: the access-pattern attack and side-channel threat model, an interactive binary tree contrasting the server's view (encrypted blobs) with the client's view (block IDs, position map) with live path highlighting, a step-by-step trace of a single READ or WRITE through position-map lookup, re-randomization, path read, stash update, greedy eviction, and write-back, a side-by-side adversary-vs-client log, and a costs/when-to-use panel with a bandwidth-overhead table and real-world deployments.\n\n## What Can Go Wrong\n\n- **Stash overflow** is possible but rare. Path ORAM guarantees O(log N) stash with high probability, but the tail is not zero. Real deployments use recursive ORAM + larger Z to push overflow probability below 2⁻⁸⁰.\n- **Timing attacks** through access latency. Browser operations are not constant-time. Production ORAMs pad all operations to constant time.\n- **Position map is O(N).** For large N, the position map doesn't fit on the client. Recursive ORAM stores it in another ORAM instance.\n- **Web Worker boundary is informational, not cryptographic.** A malicious client-side script could bypass it. In production, the server is a physically separate machine.\n- **Semi-honest security only.** An actively malicious server can return wrong blocks, fork the tree, or drop writes. Malicious-secure ORAMs (Ring ORAM, MI-ORAM) add MACs and version counters.\n- **Side-channels in the browser.** Cache timing, memory allocation patterns, garbage collection can leak information. Production ORAMs run in constant-time hardware.\n\n## Real-World Usage\n\n- Introduced by Stefanov, van Dijk, Shi, Fletcher, Ren, Yu, and Devadas at CCS 2013; extended JACM 2018.\n- Deployed in Intel SGX Ascend secure processors and Maas FPGA secure designs.\n- Used in ZeroTrace, Obliviate, and Obladi (oblivious OLTP databases).\n- Built on the Goldreich–Ostrovsky theorem (1987, 1996) proving logarithmic ORAM overhead.\n- The 16-line pseudocode makes Path ORAM the simplest practical ORAM construction.\n\n## How to Run Locally\n\n```bash\ngit clone https://github.com/systemslibrarian/crypto-lab-oram-vault\ncd crypto-lab-oram-vault\nnpm install\nnpm run dev\n```\n\n## Related Demos\n\n- [crypto-lab-oblivious-shelf](https://systemslibrarian.github.io/crypto-lab-oblivious-shelf/) — 2-server IT-PIR hides a single query index instead of access patterns.\n- [crypto-lab-patron-shield](https://systemslibrarian.github.io/crypto-lab-patron-shield/) — IT-PIR applied to library catalog privacy.\n- [crypto-lab-psi-gate](https://systemslibrarian.github.io/crypto-lab-psi-gate/) — private set intersection for contact discovery.\n- [crypto-lab-silent-tally](https://systemslibrarian.github.io/crypto-lab-silent-tally/) — Shamir-based MPC secure sum.\n\n## Five Exhibits\n\n1. **Why Encryption Alone Isn't Enough** — the access-pattern attack, side-channel threat model, what ORAM prevents\n2. **Tree Visualization** — interactive binary tree showing server view (encrypted blobs) vs. client view (block IDs, position map), live path highlighting during accesses\n3. **Access Walkthrough** — step-by-step trace of a single READ or WRITE: position-map lookup, re-randomization, path read, stash update, greedy eviction, write-back\n4. **Adversary vs. Client** — side-by-side log of what the server observes (uniform random paths) vs. what the client actually did (specific block accesses)\n5. **Costs and When to Use** — bandwidth overhead table, use-case guide, real-world deployments, cross-links to related labs\n\n## Protocol Implementation\n\nImplements Algorithm 1 from the 2018 JACM paper exactly:\n\n```\nAccess(op, a, data*):\n  1. x ← position[a]\n  2. position[a] ← uniform random leaf\n  3. Read path P(x) from server\n  4. Decrypt all blocks → add real blocks to stash\n  5. if READ: data ← stash[a]\n     if WRITE: stash[a] ← data*\n  6. Greedy eviction: write back path P(x) with fresh-nonce encryption\n  7. Return data\n```\n\nEvery access reads AND writes a full path. The position map update is\nAFTER reading and BEFORE writing back. Block re-encryption uses fresh\nnonces so the server cannot link pre-access to post-access ciphertexts.\n\n## Testing\n\nThe protocol modules ship with a Vitest suite (`npm test`) that asserts both the\n**correctness** and the **security properties** the demo claims — not just that the\ncode runs:\n\n- **Encryption** — AES-256-GCM round-trips; a fresh 96-bit nonce per encryption (no\n  reuse); dummy blocks are byte-shaped like real blocks yet decrypt to `null`;\n  tampered ciphertext and wrong-key blocks are rejected by the GCM tag.\n- **Correctness** — every block initializes to zero and is recoverable;\n  read-after-write; independent blocks never corrupt one another; last-write-wins; a\n  200-step randomized workload is checked against a plaintext reference model.\n- **Obliviousness** — every access is exactly one full path read + one full path\n  write; the server log holds only `{bucketId, operation, timestamp}` (never block\n  ids); a READ and a WRITE produce a byte-identical server footprint; the accessed\n  block is re-randomized to a fresh leaf each access; repeatedly hitting one block\n  yields a near-uniform path distribution (χ² goodness-of-fit, df=15).\n- **Bounded stash** — the high-water mark stays well within bound across a\n  1000-access workload (the live demo surfaces this as the \"Stash Peak\" stat).\n- **UI smoke** — `main.ts` boots under happy-dom with every wired control resolving,\n  tab switching works, and a READ flows end-to-end and renders the tree.\n\n```bash\nnpm run typecheck   # tsc --noEmit over src + tests\nnpm test            # vitest run (26 tests)\nnpm run test:coverage\n```\n\nCI (`.github/workflows/deploy.yml`) gates deployment on type-check + tests before\nbuilding and publishing to Pages.\n\n## Stack\n\nVite · TypeScript strict · Vanilla CSS · Web Crypto API · Vitest · GitHub Pages\n\n---\n\n*One of 120+ browser demos in the [Crypto Lab](https://crypto-lab.systemslibrarian.dev/) suite.*\n\n*\"So whether you eat or drink or whatever you do, do it all for the glory of God.\" — 1 Corinthians 10:31*\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsystemslibrarian%2Fcrypto-lab-oram-vault","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsystemslibrarian%2Fcrypto-lab-oram-vault","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsystemslibrarian%2Fcrypto-lab-oram-vault/lists"}