Home / Docs / Creating and writing a vault from JavaScript

Surface: a page on a *.sgit.ai site, outside every vault host. The other surfaces →

Creating, opening and writing a vault from JavaScript

A web page that wants its own vault (newsroom.sgit.ai keeping a reader's notes, a tool saving its output) needs the same five actions the CLI has: create, open, read, write and commit, push. All five already exist in the browser, in the library that runs dev.vault.sgraph.ai. This page is the recommendation to use that library and nothing else, the exact methods for each action, and a technical account of what goes over the wire. Reading one file with a read key is the read-only half of the same story.

Checked on 12 October 2026. The library is vault UI v0.2.3 (sgraph_ai_app_send__ui__vault/v0/v0.2/v0.2.3/_common/js/lib/ in SGraph-AI__App__Send); the twelve files served by dev.vault.sgraph.ai are byte-identical to that folder. Every code sample below was run: create, write and push with the library, sgit clone and sgit push with sgit-ai 0.21.0, then open and read back with the library.

The recommendation: one code base

So a site does not write its own vault writer, and does not copy one from the tools modules. Two ports drift: the tools port needed its own fix before it could open vaults made by sgit 0.16, and the format is moving again with 0.19 to 0.21. Gaps found by using the library are fixed in the library, in SGraph-AI__App__Send, and every site picks them up.

Loading the library

The files are plain scripts, not ES modules: each declares a global class, and the sg-vault--*.js files add methods to SGVault.prototype. Order matters. A classic <script src> from another origin needs no CORS, so this works on any page:

<script src="https://dev.vault.sgraph.ai/_common/js/lib/sg-send/sg-send-crypto.js"></script>
<script src="https://dev.vault.sgraph.ai/_common/js/lib/sg-send/sg-send.js"></script>
<script src="https://dev.vault.sgraph.ai/_common/js/lib/sg-vault/sg-vault-crypto.js"></script>
<script src="https://dev.vault.sgraph.ai/_common/js/lib/sg-vault/sg-vault-object-store.js"></script>
<script src="https://dev.vault.sgraph.ai/_common/js/lib/sg-vault/sg-vault-ref-manager.js"></script>
<script src="https://dev.vault.sgraph.ai/_common/js/lib/sg-vault/sg-vault-commit.js"></script>
<script src="https://dev.vault.sgraph.ai/_common/js/lib/sg-vault/sg-vault.js"></script>
<script src="https://dev.vault.sgraph.ai/_common/js/lib/sg-vault/sg-vault--file-ops.js"></script>
<script src="https://dev.vault.sgraph.ai/_common/js/lib/sg-vault/sg-vault--folder-ops.js"></script>
<script src="https://dev.vault.sgraph.ai/_common/js/lib/sg-vault/sg-vault--sync.js"></script>
<script src="https://dev.vault.sgraph.ai/_common/js/lib/sg-vault/sg-vault--history.js"></script>
<script src="https://dev.vault.sgraph.ai/_common/js/lib/sg-vault/sg-vault--branches.js"></script>

Three things to know about that list:

• The path is not versioned. Every deploy of the vault UI overwrites it. A site that must not change under its readers (any site holding keys, newsroom.sgit.ai included) copies these twelve files into its own repo at a known commit and loads them from its own origin; the passkey design already requires that. It is still one code base: the copy is pinned, never edited, and refreshed from upstream.
• The API takes any origin. Measured against dev.send.sgraph.ai: the preflight answers access-control-allow-origin: * and allows x-sgraph-access-token and x-sgraph-vault-write-key. Do not add X-API-Key to a browser request (the Python CLI sends it); it is not on the allowed list, so the preflight fails and nothing is sent.
• Web Crypto needs a secure context, https or localhost. Key derivation is two PBKDF2 runs of 600,000 iterations, done in parallel: about a second on a laptop, more on a phone, once per open.

The five actions

1 · Create a vault

const sgSend = new SGSend({ endpoint: 'https://dev.send.sgraph.ai', token: accessToken })
const passphrase = randomPassphrase()                 // 24 chars of [a-z0-9], as sgit init makes
const vault = await SGVault.create(sgSend, passphrase, { name: 'My notes' })
const vaultKey = vault.getVaultKey()                  // "<passphrase>:<vault_id>": store it, it is the only way back in

function randomPassphrase(n = 24) {
  const abc = 'abcdefghijklmnopqrstuvwxyz0123456789', out = []
  while (out.length < n) {                             // rejection sampling: no modulo bias
    for (const b of crypto.getRandomValues(new Uint8Array(n))) if (b < 252 && out.length < n) out.push(abc[b % 36])
  }
  return out.join('')
}

create picks a random 8-character vault id, derives the keys, and sends the first commit, the named ref, the clone ref and the branch index as one POST /batch. There is no separate "create vault" endpoint: the server creates the vault on the first write and remembers the SHA-256 of the write key that made it, and from then on only that write key can write. The write needs an access token, so creating a vault needs an access token; opening and reading do not.

The passphrase is the caller's to choose, and its strength is the vault's strength: there is no rate limit on guessing it offline. Use 24 random characters as above, the same shape sgit init generates. The vault's display name is stored encrypted, in .vault-settings.json.

2 · Open a vault

const vault = await SGVault.open(sgSend, vaultKey, { cloneBranch: deviceBranch })   // see the box below
vault.writable        // true: a vault key carries the write key
vault.name            // decrypted from .vault-settings.json
vault.listFolder('/') // [{ name, type: 'file'|'folder', size, content_hash }]

open reads the branch index, then the named ref live (refs are never cached), then this browser's clone ref, and loads the root folder. Sub-folders load lazily. If the CLI or another browser published while this one sat still, open shows the newer published head rather than the stale clone. A key copied from sgit output carries a prefix (sgit_private_vault_ followed by the key); open does not strip it, so pass the key through SGVaultCrypto.stripKeyPrefix() first. For a read key instead of a vault key, see read-only access.

3 · Read a file

async function ensureLoaded(vault, folder) {          // load every folder on the path
  let path = ''
  for (const part of folder.split('/').filter(Boolean)) {
    path += '/' + part
    if (vault.needsLoading(path)) await vault.loadSubTreeOnDemand(path)
  }
}
await ensureLoaded(vault, '/notes')
const bytes = await vault.getFile('/notes', 'today.md')  // ArrayBuffer, decrypted
const text  = new TextDecoder().decode(bytes)

Files are addressed as (folder, name), folder paths start with /. Files over 4 MB are fetched through a presigned S3 URL automatically.

4 · Write: every write is a commit

async function writeFile(vault, folder, name, data) {
  await ensureLoaded(vault, folder)                       // REQUIRED, see the warning below
  let path = ''
  for (const part of folder.split('/').filter(Boolean)) { // create missing folders
    path += '/' + part
    if (!vault.listFolder(path)) await vault.createFolder(path)
  }
  const bytes  = typeof data === 'string' ? new TextEncoder().encode(data) : data
  const exists = (vault.listFolder(folder) || []).some(e => e.name === name && e.type === 'file')
  return exists ? vault.updateFile(folder, name, bytes) : vault.addFile(folder, name, bytes)
}
await writeFile(vault, '/notes', 'today.md', '# Today\n')

There is no staging area, and no separate commit call. addFile, updateFile, removeFile, renameFile, moveFile, createFolder and the other folder operations each make one commit, with a generated message such as Add today.md, and send the blob, the changed trees, the commit and the clone ref as one POST /batch. addFiles([{ folderPath, fileName, fileData }]) writes many files as one commit. A commit lands on this browser's private clone branch; nobody else sees it until it is pushed.

5 · Push: publish with compare-and-swap

async function publish(vault) {
  if (vault._refManager.lastRawRef(vault._refFileId) === undefined)
    await vault.getBehindCount()               // only if never read: arms the compare-and-swap
  try { await vault.pushIfMatch(); return }
  catch (e) { if (e.code !== 'ECAS') throw e } // somebody else published first
  const theirs = await vault._refManager.readRef(vault._refFileId)
  const r = await vault.merge(theirs, { publish: false })   // fast-forward or three-way, file level
  if (r.conflicts.length) throw new Error('conflicts: ' + r.conflicts.join(', '))
  await vault.pushIfMatch()
}

pushIfMatch() moves the named ref only if the server still holds the exact bytes this client last read for it. If someone else published in between, it throws ECAS and the caller merges and retries. That is the pattern the vault host's own headless kernel uses (kernel-app-handlers.js, _safePush), and the two _refManager calls are copied from it, which is why they reach into an underscore field; a public safePush() is on the upstream list.

• Do not call push(). It moves the named ref unconditionally, which silently drops whatever another client published since your last read. The vault UI's shells still call it; the CLI reports the result as a rewind.
• Read the ref once after create, and only then. A new vault has only ever written its named ref, so pushIfMatch throws ENOMATCH until something reads it; open has already read it. But any read re-arms the comparison: calling getBehindCount() or readRef immediately before every pushIfMatch compares against the bytes just fetched, which turns the compare-and-swap into a blind overwrite. That is why publish reads only when the ref has never been read. Tested with two writers racing on 12 October 2026: with the guard, the second gets ECAS, merges, and both changes survive; without it, the first writer's commit is lost.
• Pull with pull() when there is nothing unpushed (it refuses otherwise), or with merge(theirs) when there is. getAheadCount() and getBehindCount() report the distance.

Read-only access

A read key, 64 hex characters plus the vault id, decrypts but cannot write:

const cred = SGVaultCrypto.parseReadOnlyCredential(readKey)   // "<64 hex>:<vault_id>", prefix optional
const c    = await SGVaultCrypto.deriveReadOnlyCreds(cred.vaultId, cred.readKeyHex)
const ro   = await SGVault.openReadOnly(new SGSend({ endpoint }), c.vaultId, c.readKeyB64, c.refFileId)
ro.writable   // false

For a page that only shows one file, the 90-line reader in Reading one file out of a vault is smaller.

The methods

Errors carry a code where the caller is expected to act: ECAS (the named ref moved: merge and retry), ENOMATCH (compare-and-swap before any read), EREADONLY (a static host, no write API). HTTP failures throw with the status and the server's detail, for example a 403 when the access token is missing.

How it works

Keys: everything comes from the vault key

The server receives none of this except the write key's hex, and stores only its hash. Addresses are computed, never looked up: a holder of the read key knows where the head is before making a request.

Objects: four kinds, all ciphertext

• Encryption. AES-256-GCM, a random 12-byte IV, stored as IV || ciphertext || tag: exactly what crypto.subtle.encrypt returns with the IV in front.
• Object ids. obj-cas-imm- + the first 12 hex of SHA-256 over the ciphertext, stored at bare/data/<id>. Content-addressed, so immutable and cacheable forever.
• Blob: the file's bytes, encrypted.
• Tree (tree_v1): { schema, entries: [{ name_enc, size_enc, content_hash_enc, blob_id, tree_id }] }. Names, sizes and hashes are encrypted one by one, so the folder listing is itself ciphertext; a sub-folder is an entry with a tree_id.
• Commit (commit_v2): { schema, parents, tree_id, timestamp_ms, message_enc, branch_id, signature }, the message encrypted.
• Ref: {"commit_id": "obj-cas-imm-…"}, encrypted, at bare/refs/<ref id>. The only mutable files are refs and the branch index.

Two refs: the clone branch and the named branch

Each client commits to its own clone ref; push copies that commit id into the named ref, which is what everyone else reads. This is the two-branch model the CLI uses, so a browser and a terminal are two clones of the same vault. The branch index (branch_index_v1) lists the branches so that sgit clone can find the named ref.

The wire

So one file write is one request carrying four or more encrypted objects, and one push is one request carrying the ref and the index. The full endpoint list is in API: vault objects, the headers in API: authentication.

With sgit 0.21: what holds and what does not

What holds, tested 12 October 2026. A vault made with SGVault.create was cloned by sgit-ai 0.21.0 with every file intact; a CLI commit and push was then opened and read back by the library; a library updateFile and pushIfMatch was pulled by the CLI, which then pushed again without complaint. For a vault at the default format, which is every vault until its owner raises it, the browser and the CLI interoperate in both directions.

What does not hold yet, from the code and History integrity:

None of that matters to a site keeping its own vaults (newsroom.sgit.ai's reader vaults are written only by newsroom.sgit.ai) as long as nobody raises their format. It matters as soon as a vault is shared with the CLI under the 0.21 policies, and the fix is in the library, not around it.

What the library needs, in SGraph-AI__App__Send

In priority order, each a change to _common/js/lib/sg-vault/ that every site then inherits:

1. Fix the lazy-folder write. A write into an unloaded folder should load it (or refuse), never commit a tree that drops the file.
2. A public safePush(): read the ref if it was never read, pushIfMatch, merge and retry once on ECAS. Then retire unconditional push().
3. A clone branch per device by default, made once and remembered, instead of the shared web-ui.
4. create(…, { vaultId }): let the caller supply the vault id. A vault whose id and passphrase are derived (the passkey's computed top vault) cannot be created through the public API today, only opened.
5. Publish at a versioned path (/_common/js/lib/v0.2.3/…, or one bundled file) so a site can pin a version without copying, and move the inline SGVault.createFromToken out of index.html. Token-style keys were dropped from the CLI in 0.15 as guessable, so new sites should not use that path at all.
6. Merge the branch index with compare-and-swap instead of overwriting it, keeping other entries, the gate, the keys and the tags.
7. Sign commits (P-256, JCS signing bytes, author_key_id; the CLI's tests/_fixtures/interop_vectors.json is the test vector), then format 2 ids when the gate says so.

For newsroom.sgit.ai

• Keys. The newsroom already stores vault keys behind a passkey (the design, passkey/lab.js for the derivation). A vault made with SGVault.create and a random passphrase goes into that keyring as getVaultKey(), and is opened next time with SGVault.open. The lab's own derivation (sgitKeys) is the same PBKDF2 as SGVaultCrypto.deriveKeys, checked against vectors generated with the CLI's own Vault__Crypto.
• The computed top vault needs item 3 above; until then it can be opened but not created by the library.
• The access token is needed for every write. Pasted once and then kept inside the reader's own vault is the shape the design already describes.
• Load a pinned copy of the twelve files from the newsroom's own origin, per the design's no-third-party-scripts rule.

Reading one file out of a vault · API: vault objects · The two-branch model · History integrity · Credentials