30:T792,md`## User Guide ### Quick Start 1. **Import** into your notebook: \`\`\`js import {secretStore} from "@tomlarkworthy/secrets" viewof mySecrets = secretStore("my-keys") \`\`\` 2. **Generate a key** — click "Generate AES Key". A 256-bit AES key is created and displayed once. **Copy it to a safe place** (password manager, env var, etc.). This is the only time you'll see it. 3. **Click Continue** to enter the secret editor. Add key-value pairs and click **Save**. The encrypted data is written into the cell's own source code — it persists across page reloads and notebook exports. 4. **Returning** — paste your AES key into the unlock field. Your browser's password manager can autofill it (the input has \`autocomplete="current-password"\`). ### How It Works - Secrets are encrypted with **AES-256-GCM** using the Web Crypto API — the gold standard for browser-side encryption. - The encrypted ciphertext and IV are stored as a JSON literal in the cell's source code: \`secretStore("name", {cipher: "...", iv: "..."})\` - **No server, no localStorage** — everything lives in the notebook file itself. - We **never derive keys from passwords**. Instead, a full 256-bit key is generated properly via \`crypto.subtle.generateKey()\`. This eliminates weak-password attacks entirely. - A fresh 12-byte IV is generated for every save, ensuring identical plaintext produces different ciphertext. ### Reactive Behavior - **Locked**: the cell value is \`undefined\`. Downstream cells remain pending — they simply don't run. - **Unlocked**: the cell value is a \`Map\`. Downstream cells recompute automatically. ### Bot / Automation Access Each secret box has a \`data-secrets\` attribute and \`.secrets\` class for programmatic access: \`\`\`js const box = document.querySelector('[data-secrets="my-keys"]'); box.querySelector('input').value = myKey; box.querySelector('.secrets-unlock').click(); \`\`\` `31:T58d,md`## Developer Documentation ### Module Structure The implementation is organized into four sections: 1. **Imports** — \`runtime\` from \`@tomlarkworthy/runtime-sdk\` for self-modification 2. **Crypto Helpers** — Base64 encoding, AES key generation/import, encrypt/decrypt 3. **UI Components** — CSS styles themed with lopecode variables, SVG padlock 4. **Secret Store Builder** — The main \`secretStore(name, data?)\` function ### Self-Modification When the user clicks Save, the cell rewrites its own source code: 1. The view element carries a unique Symbol tag (\`_secretsTag\`) 2. \`selfModify()\` searches \`runtime._variables\` for the variable whose \`_value\` has that tag 3. Once found, it reads the variable's input names and constructs a new function: \`secretStore("name", {cipher: "...", iv: "..."})\` 4. \`variable.define()\` replaces the cell definition — the Observable runtime re-evaluates it with the embedded ciphertext ### Key Design Decisions - **No localStorage** — ciphertext lives in source code, survives export - **No password derivation** — full AES-256 key generation avoids weak-password attacks - **Symbol-based self-discovery** — each instance has a unique tag for finding its own variable, enabling multiple independent stores - **viewof pattern** — locked state is \`undefined\` (pending), unlocked is \`Map\`, giving natural reactive behavior `32:T2182,secretStore = { const _runtime = runtime; return function secretStore(name, data) { const tag = Symbol("secrets-" + name); const state = { map: null, savedData: data, dirty: false, cryptoKey: _activeKeys.get(name) || null, unlocked: false }; const root = htl.html`

${secretsStyle.cloneNode(true)}

${padlockSVG.cloneNode(true)}

${name}

`; root._secretsTag = tag; const body = root.querySelector(".secrets-body"); function dispatchValue() { root.value = state.unlocked ? state.map : undefined; root.dispatchEvent(new Event("input", { bubbles: true })); } async function unlock(cryptoKey) { state.cryptoKey = cryptoKey; _activeKeys.set(name, cryptoKey); state.map = await decryptMap(data, cryptoKey); state.unlocked = true; state.dirty = false; root.classList.remove("locked"); root.classList.add("unlocked"); renderUnlocked(); dispatchValue(); } async function selfModify(newData) { let viewofVar = null; for (const v of _runtime._variables) { try { if (v._value && v._value._secretsTag === tag) { viewofVar = v; break; } } catch (e) {} } if (!viewofVar) throw new Error("Could not find own variable"); const inputNames = viewofVar._inputs.map((i) => i._name).filter(Boolean); const dataLiteral = JSON.stringify(newData); const newDef = Function( ...inputNames, `"use strict"; return secretStore(${JSON.stringify( name )}, ${dataLiteral})` ); console.log("[secrets] Redefining cell with ciphertext"); viewofVar.define(viewofVar._name, inputNames, newDef); } function renderLocked() { if (data) { // Auto-unlock if we have a cached key if (state.cryptoKey) { unlock(state.cryptoKey).catch(() => { // Key was invalid (maybe data changed), clear cache and show input _activeKeys.delete(name); state.cryptoKey = null; renderLocked(); }); return; } body.innerHTML = ""; const row = htl.html`

`; body.append(row); const input = body.querySelector("input"); const btn = body.querySelector(".secrets-unlock"); const errEl = body.querySelector(".secrets-error"); async function doUnlock() { try { errEl.style.display = "none"; const cryptoKey = await importAESKey(input.value.trim()); await unlock(cryptoKey); } catch (e) { errEl.textContent = "Decryption failed \u2014 wrong key?"; errEl.style.display = "block"; } } btn.onclick = doUnlock; input.onkeydown = (e) => { if (e.key === "Enter") doUnlock(); }; } else { body.innerHTML = ""; const gen = htl.html`

No secrets stored yet.

`; body.append(gen); const btn = gen.querySelector(".secrets-generate"); const keyDisplay = gen.querySelector(".secrets-generated-key"); btn.onclick = async () => { const base64Key = await generateAESKey(); state.cryptoKey = await importAESKey(base64Key); _activeKeys.set(name, state.cryptoKey); state.map = new Map(); state.unlocked = true; state.dirty = true; keyDisplay.textContent = base64Key; keyDisplay.style.display = "block"; btn.style.display = "none"; const copyBtn = htl.html``; copyBtn.onclick = () => { navigator.clipboard.writeText(base64Key); copyBtn.textContent = "Copied!"; setTimeout(() => { copyBtn.textContent = "Copy key to clipboard"; }, 1500); }; keyDisplay.after(copyBtn); const continueBtn = htl.html``; continueBtn.onclick = () => { root.classList.remove("locked"); root.classList.add("unlocked"); renderUnlocked(); dispatchValue(); }; copyBtn.after(continueBtn); }; } } function renderUnlocked() { body.innerHTML = ""; const table = htl.html`

Key	Value

`; const tbody = table.querySelector("tbody"); function renderRows() { tbody.innerHTML = ""; for (const [k, v] of state.map) { const masked = { is: true }; const valCell = htl.html`••••••••`; valCell.onclick = () => { if (masked.is) { valCell.textContent = v; valCell.classList.remove("masked"); } else { valCell.textContent = "\u2022\u2022\u2022\u2022\u2022\u2022\u2022\u2022"; valCell.classList.add("masked"); } masked.is = !masked.is; }; const copyBtn = htl.html``; copyBtn.onclick = () => { navigator.clipboard.writeText(v); copyBtn.textContent = "\u2713"; setTimeout(() => { copyBtn.textContent = "\uD83D\uDCCB"; }, 1000); }; const delBtn = htl.html``; delBtn.onclick = () => { state.map.delete(k); state.dirty = true; renderRows(); updateSaveButton(); dispatchValue(); }; const row = htl.html` ${k} ${valCell} ${copyBtn} ${delBtn} `; tbody.append(row); } } renderRows(); const addRow = htl.html`

`; const [keyIn, valIn] = addRow.querySelectorAll("input"); addRow.querySelector("button").onclick = () => { const k = keyIn.value.trim(); const v = valIn.value; if (!k) return; state.map.set(k, v); state.dirty = true; keyIn.value = ""; valIn.value = ""; renderRows(); updateSaveButton(); dispatchValue(); }; const saveBtn = htl.html``; saveBtn.onclick = async () => { try { saveBtn.textContent = "Saving..."; const newData = await encryptMap(state.map, state.cryptoKey); console.log("[secrets] Encrypted, now self-modifying...", newData); await selfModify(newData); console.log("[secrets] Self-modification complete"); } catch (e) { console.error("[secrets] save failed:", e); saveBtn.textContent = "Save failed!"; setTimeout(() => { saveBtn.textContent = "Save"; }, 2000); } }; function updateSaveButton() { saveBtn.style.display = state.dirty ? "" : "none"; } const actions = htl.html`

${saveBtn}

`; body.append(table, addRow, actions); updateSaveButton(); } root.value = undefined; renderLocked(); return root; }; }33:Tfe3,secretsStyle = md``34:[] 2e:{"title":"Secrets","cells":[{"id":157,"value":"","pinned":false,"hidden":false,"mode":"html"},{"id":116,"value":"viewof secrets = secretStore(\"secrets\")","pinned":false,"hidden":false,"mode":"ojs"},{"id":98,"value":"md`\n\nEncrypted key-value storage that lives in the notebook's own source code. Secrets are protected with AES-256-GCM.\n\n${\n isOnObservableCom()\n ? md`⚠️ doesn't work on Observable until you [export](https://observablehq.com/@tomlarkworthy/exporter-2)`\n : \"\"\n}\n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":99,"value":"$30","pinned":false,"hidden":false,"mode":"ojs"},{"id":100,"value":"$31","pinned":false,"hidden":false,"mode":"ojs"},{"id":101,"value":"md`---\n## Implementation`","pinned":false,"hidden":false,"mode":"ojs"},{"id":102,"value":"md`### Secret Store Builder\n\nThe main \\`secretStore(name, data?)\\` function. Creates an encrypted key-value store view. Closes over \\`runtime\\` for self-modification on save.`","pinned":false,"hidden":false,"mode":"ojs"},{"id":103,"value":"$32","pinned":false,"hidden":false,"mode":"ojs"},{"id":115,"value":"_activeKeys = new Map()","pinned":false,"hidden":false,"mode":"ojs"},{"id":104,"value":"md`### Crypto Helpers\n\nBase64 encoding/decoding and AES-256-GCM key management. All crypto operations use the Web Crypto API (\\`crypto.subtle\\`).`","pinned":false,"hidden":false,"mode":"ojs"},{"id":105,"value":"fromBase64 = str => Uint8Array.from(atob(str), c => c.charCodeAt(0)).buffer","pinned":false,"hidden":false,"mode":"ojs"},{"id":106,"value":"generateAESKey = async () => {\n const key = await crypto.subtle.generateKey({\n name: 'AES-GCM',\n length: 256\n }, true, [\n 'encrypt',\n 'decrypt'\n ]);\n const raw = await crypto.subtle.exportKey('raw', key);\n return toBase64(raw);\n}","pinned":false,"hidden":false,"mode":"ojs"},{"id":107,"value":"importAESKey = async base64Key => {\n const raw = fromBase64(base64Key);\n return crypto.subtle.importKey('raw', raw, { name: 'AES-GCM' }, false, [\n 'encrypt',\n 'decrypt'\n ]);\n}","pinned":false,"hidden":false,"mode":"ojs"},{"id":108,"value":"encryptMap = async (map, cryptoKey) => {\n const plaintext = new TextEncoder().encode(JSON.stringify(Object.fromEntries(map)));\n const iv = crypto.getRandomValues(new Uint8Array(12));\n const ciphertext = await crypto.subtle.encrypt({\n name: 'AES-GCM',\n iv\n }, cryptoKey, plaintext);\n return {\n cipher: toBase64(ciphertext),\n iv: toBase64(iv)\n };\n}","pinned":false,"hidden":false,"mode":"ojs"},{"id":109,"value":"decryptMap = async (data, cryptoKey) => {\n const ciphertext = fromBase64(data.cipher);\n const iv = fromBase64(data.iv);\n const plaintext = await crypto.subtle.decrypt({\n name: 'AES-GCM',\n iv\n }, cryptoKey, ciphertext);\n return new Map(Object.entries(JSON.parse(new TextDecoder().decode(plaintext))));\n}","pinned":false,"hidden":false,"mode":"ojs"},{"id":110,"value":"toBase64 = buffer => btoa(String.fromCharCode(...new Uint8Array(buffer)))","pinned":false,"hidden":false,"mode":"ojs"},{"id":111,"value":"md`### UI Components\n\nThemed styles using lopecode CSS variables and an SVG padlock with lock/unlock animation.`","pinned":false,"hidden":false,"mode":"ojs"},{"id":112,"value":"padlockSVG = htl.svg``","pinned":false,"hidden":false,"mode":"ojs"},{"id":113,"value":"$33","pinned":false,"hidden":false,"mode":"ojs"},{"id":114,"value":"md`### Imports\n\nRuntime SDK provides access to \\`runtime._variables\\` for self-modification.`","pinned":false,"hidden":false,"mode":"ojs"},{"id":117,"value":"import { runtime, isOnObservableCom } from \"@tomlarkworthy/runtime-sdk\"","pinned":false,"hidden":false,"mode":"ojs"}],"files":"$W34","stdlib":"1","titling":"auto"}