SDK
open
How geode.open fetches and decrypts a stored file, with a shared key or from the vault, what it returns and the errors it raises.
open(id: string, key?: string): Promise<OpenResult>open fetches a ciphertext by its Irys id and decrypts it on the device. With a key it opens any Geode file and never touches the wallet. Without a key it looks the key up in the vault's manifest.
- Seal
- Quote
- Prove
- Pay
- Store
- Open
What it does
Find the key
With
key, the client uses it as given. Without it, the client unlocks the vault on first use (the wallet signs the key message and the manifest is read, as inrecover) and takes the key of the entry whoseidmatches. No matching entry raisesNOT_FOUND.Fetch the ciphertext
The id must be 43 base64url characters. The client reads
/configonce per client, even whengatewayUrlis set in the options, then fetches<gateway>/<id>, where the gateway isgatewayUrlfrom the options or else from/config. A ciphertext larger than 64 MiB, by itsContent-Lengthor its bytes, raisesPAYLOAD_TOO_LARGE.Unseal
The client checks the
GEODE001header and that the length is a bucket, decrypts every chunk with XChaCha20-Poly1305 under the file key, and reads the name, media type and exact length from inside the ciphertext. A wrong or malformed key, or a changed byte, raisesWRONG_KEY.
A client created without a wallet opens files with a key; it needs only relayerUrl.
Arguments
idrequiredstringStoreResult.id.keystringReturn value
bytesUint8Array<ArrayBuffer>BlobPart, so new Blob([bytes], { type }) makes a file of it.namestringtypestringWhat it costs
Nothing. open reads a public ciphertext from the gateway and sends no transaction. Neither the key nor the plaintext enters a request.
Errors
| Code | Raised when |
|---|---|
WRONG_KEY | The key is not 43 base64url characters or does not decrypt the ciphertext |
VALIDATION_ERROR | The id is not 43 base64url characters |
NOT_FOUND | No key is given and the vault has no entry with this id, or the gateway has no ciphertext with this id (it answers 404) |
IRYS_UNAVAILABLE | The gateway answers any other non-success status |
PAYLOAD_TOO_LARGE | The ciphertext is larger than 64 MiB |
CONFIGURATION_REQUIRED | Neither the options nor /config give a gateway URL |
WALLET_REJECTED | No key is given and the client has no wallet, or the wallet declines the key message |
UNKNOWN_ROOT, RELAYER_FAILED | No key is given and the vault cannot be unlocked: the tree does not hash to its root, or a relayer reply does not match the contract |
UPSTREAM_UNAVAILABLE | A network failure or any other unrecognised error |
Codes from /config, and without a key from /manifest and /tree, pass through as listed at /docs/api#errors.
Samples
Open a share link, with no wallet:
import { createGeode } from '@geode/sdk'
const reader = createGeode({ relayerUrl: 'https://api.geode.directory' })
// A share link has the form /s/<id>#<key>.
const id = decodeURIComponent(location.pathname.slice('/s/'.length))
const key = location.hash.slice(1)
const { bytes, name, type } = await reader.open(id, key)
const opened = new File([bytes], name, { type })Open a file from the vault and save it:
const { bytes, name, type } = await geode.open(id)
const url = URL.createObjectURL(new Blob([bytes], { type }))
const a = document.createElement('a')
a.href = url
a.download = name
a.click()
URL.revokeObjectURL(url)