/packages/changelog/
Changelog
All notable changes to JSVola. The format follows
Keep a Changelog and the project uses
Semantic Versioning. Every @vol-a/* package (named @vola/* up to 1.0.0) and the
Docker image share one version.
- The website says how fresh it is. The footer of every page, the docs’ included, shows
the version, the date of its release tag, when the site was built (UTC) and the commit;
the Packages table has an On npm column with the date each package’s newest version
was published there, and that version when it is not the repository’s (not on npm yet
while a package has never been published). Read once per build
(
apps/website/src/build-info.mjs); the registry never fails the build, andSITE_NPM=offbuilds without asking it (apps/website/README.md). - Running without the image is documented:
node dist/server.jsandnode dist/worker.jsof a built checkout as two services, and what the image would otherwise set (docs/DEPLOYMENT.md).https://examples.vol-a.com, the production examples site, runs that way (deploy/examples/prod.sh, two systemd user units); the website’s “live examples” links now open it.
Changed
Section titled “Changed”@jsudc/*0.3 (@jsudc/core0.3.0,@jsudc/server0.3.0,@jsudc/react0.3.1, the lookups androw_linkrelease) in@vol-a/server,@vol-a/client,@vol-a/react, the examples site and the website. Nothing changes on the wire: thefilescollection’s rows, filters, cursors andGET /vola/udc/subscribeare as before.@jsudc/server0.3 checks at startup that everylookupfield names a served collection; vola’skind,encryptionandprocessing_statusare lookups intolookups.yaml, which name none, so@vol-a/serverturns that check off and runs it itself without them (udc/links.ts): any other lookup orrow_linkof the registry still stops the start when it does not fit.@jsudc/server0.3 still has no transport forcapabilities.subscribe, so vola’s own stays (docs/REALTIME.md).@vol-a/react’s@jsudc/coreand@jsudc/reactpeer ranges are^0.2.0 || ^0.3.0(were^0.2.0): an application embedding it can stay on@jsudc/*0.2 or move to 0.3, with@jsudc/reactand@jsudc/corefrom the same line. The tutorial program (apps/tutorial/ticket-desk) stays on 0.2, because its chapters show itspackage.json.
1.1.0 - 2026-11-15
Section titled “1.1.0 - 2026-11-15”SQLite as a database option. A small installation on one host can run vola on a single
SQLite file (VOLA_DATABASE_URL=file:<path>), with no database service and, if it does
without background jobs, no Redis. PostgreSQL stays the default and the full-featured option.
Every API route, answer and error code is the same on both. For the HTTP API, the CLI, the
image and their configuration, this release only adds things. Code that embeds
@vol-a/server and reaches into its database handle has two type changes, listed under
Breaking for code that embeds the server below. The version is still minor because no
@vol-a/* package had been published to npm before this release.
- SQLite as a database option. Set
VOLA_DATABASE_URL=file:<path>(relative to the working directory),file:///abs/path, or:memory:for tests, in place ofpostgresql://…. The guide is docs/SQLITE.md: which database fits, the quick start without Docker, embedding the plugin, the worker, backups, the limits. The features by database are also in the README. What SQLite gives:- Every feature of the API, with the same routes, answers and error codes: files, folders,
versions, shares, tus uploads, the four encryption modes, UDC lists and
subscribe, statistics, transfer, and the CLI (vola migratecreates and migrates the file). - The driver is Node’s built-in
node:sqlite(Node 24+), so there is no new dependency. The database runs in WAL mode withforeign_keys = ON. There is one writer at a time: every transaction isBEGIN IMMEDIATE, and the server’s transactions take turns. Reads outside a transaction use a second, read-only connection. - One server process per file. Without Redis everything runs inline: thumbnails render
on
/thumb, and no OCR job is created. WithVOLA_REDIS_URLset, one worker process on the same host opens the same file and runs thumbnail and OCR jobs as on PostgreSQL:- its writes are single statements, and tesseract runs with no transaction open;
- a process waiting for the other’s write lock waits on a timer, up to 10 s, instead of
inside SQLite’s
busy_timeout, so it keeps serving; - the expired-upload sweep stays in the server, because the upload a tus
PATCHstreams into is guarded in the server’s memory (409 upload_locked, as on PostgreSQL); - only
:memory:refuses a worker:VOLA_WORKER_ENABLED=truewith it is a configuration error.
- The OCR text search on SQLite has the same API as on PostgreSQL. The
ocrfilter with words searches a contentless FTS5 index,drizzle-sqlite/0001_ocr_fts.sql(unicode61,remove_diacritics 0). Triggers keep the index in step withvola_file_metadata, and the migration indexes text already there.- Search rules: every word must occur, case-insensitively, with no stemming and no
ranking. Diacritics are kept (
č≠c), and the first 500 000 characters are indexed, as withocr_tsv. - One difference: any character that is not a letter or a digit separates words
(
e-mailiseandmail). - The server quotes the words, so FTS5 syntax typed by a user is plain text. It refuses to open a SQLite database built without FTS5 (Node’s built-in one has it).
- Search rules: every word must occur, case-insensitively, with no stemming and no
ranking. Diacritics are kept (
- Its own migration set,
packages/server/drizzle-sqlite/, shipped in the package. The server applies it at start, andvola migrateby hand, as with the PostgreSQL set.pnpm db:generatewrites both.
- Every feature of the API, with the same routes, answers and error codes: files, folders,
versions, shares, tus uploads, the four encryption modes, UDC lists and
Breaking for code that embeds the server
Section titled “Breaking for code that embeds the server”These are two exports of @vol-a/server. They do not affect the HTTP API, the CLI, the
image or the configuration.
DatabaseHandlecarriesdialectinstead ofpool(node-postgres’pg.Pool).Databaseis drizzle’s query builder without the driver:PgDatabase<PgQueryResultHKT, …>instead ofNodePgDatabase, so its type no longer has$client.
Code that reached for handle.pool or db.$client uses handle.db for queries and
handle.close() on shutdown.
Changed
Section titled “Changed”VOLA_DATABASE_URL/VOLA_DATABASE_URL_TESTacceptfile:<path>and:memory:next topostgres(ql)://.connect(url)picks the database from the URL scheme. Any other scheme throws aConfigErrorthat names the scheme and never the rest of the URL.@vol-a/server’s database layer goes through one dialect seam,db/dialect.ts, withdb/postgres.tsanddb/sqlite.tsbehind it. What is not portable goes through the seam: the advisory lock on a content hash, unique-violation and lock-not-available errors,count(*) filter, JSON fields,LIKE/ILIKE,FOR UPDATE NOWAIT,ON CONFLICT … DO NOTHINGand the OCR text match (ocrMatch(words)).capabilitiessays what a dialect has (rowLocks,ocrSearch). On PostgreSQL the SQL is the same as in 1.0.1.- The tables exported from
db/schema.tsare those of the database the process connected to (db/schema-postgres.tsordb/schema-sqlite.ts, with the same row types), so a process speaks one dialect. resolveJobsMode’s input takesmemoryDatabase: an in-memory SQLite is alwayssync.- The server and CLI test suites run on both databases (Vitest projects
server/server-sqlite,cli/cli-sqlite).VOLA_TEST_DIALECT=postgres|sqliteruns one (docs/CONTRIBUTING.md).
1.0.1 - 2026-11-04
Section titled “1.0.1 - 2026-11-04”The packages are renamed from @vola/* to @vol-a/* — @vol-a/core, @vol-a/lookups,
@vol-a/server, @vol-a/client, @vol-a/react, @vol-a/cli — because the vola scope on npm
is taken; the npm organisation is vol-a, like the site vol-a.com. This is the first npm
publication (1.0.0 went out as the Docker image and the GitHub release only). Nothing else
changes: the CLI is still vola, the image is still ghcr.io/digital-cube/jsvola, the
variables VOLA_*, the /vola prefix, the vola_* tables and the X-Vola-* headers stay.
Changed
Section titled “Changed”- Every package name, import,
--filterand the source export condition (@vol-a/source): replace@vola/with@vol-a/in an application’spackage.jsonand imports. The entries below 1.0.0 keep the names the packages had then. - The tutorial’s tarballs are
vol-a-core-1.0.1.tgz,vol-a-client-1.0.1.tgzandvol-a-react-1.0.1.tgz; the chapters show the program with the new names.
1.0.0 - 2026-11-04
Section titled “1.0.0 - 2026-11-04”The first release: the TypeScript port of vola-spp, complete per docs/PLAN.md — content-addressable, multi-tenant file storage with folders, versions, slugs, resumable uploads, thumbnails, OCR, share links, statistics, admin transfer, live lists, encryption at rest in four modes, a fetch SDK, React components, an examples site and one Docker image. Built in eight phases, one ticket each; the detailed entries below follow them, newest first.
| phase | what | ticket |
|---|---|---|
| 1.1 | monorepo scaffold (pnpm, Turbo, Biome, Vitest), compose, Dockerfile, CI, health, VOLA_* config |
TCKW73Q7EJ |
| 1.2 | tenants, API keys with scopes, auth, admin keys with X-Tenant-Slug, CLI, /keys |
TCKMP7M57K |
| 2.1 | CAS storage: streaming upload with dedup, download with Range/206 and HEAD, slugs, soft delete, purge |
TCK5HPYMY2 |
| 2.2 | virtual folders, path routes, move and rename, version chains, visibility, anonymous /public |
TCKM5DHJTH |
| 2.3 | resumable uploads: tus 1.0 at /uploads |
TCKNPKC9XY |
| 3.1 | @vola/lookups, the UDC files collection, /instance-types |
TCKUHMFRRQ |
| 3.2 | real-time: UDC subscribe over WebSocket |
TCKFQMCFDT |
| 4.1 | BullMQ worker, processing jobs, thumbnails (images and PDF) with the 202 rule |
TCKXQCJ2YY |
| 4.2 | OCR (tesseract + pdftoppm), vola_file_metadata, full-text filter |
TCKPK3YTKR |
| 5.1 | share links (token, argon2 password, expiry, max_downloads, revoke, folder shares) and statistics |
TCKKQHMDJT |
| 5.2 | admin transfer of instances between tenants, optional memento audit trail | TCK59T5P65 |
| 6.1 | encryption I: the JSV segmented format, a key per file, the tenant provider |
TCKK5UTHJX |
| 6.2 | encryption II: the keyring (PIN) provider, unlock tokens, brute force, recovery, reset, encrypted folders |
TCKFT692JH |
| 6.3 | encryption III: the caller provider, sealed resumable uploads, encrypted thumbnails and OCR, share grants, client blobs |
TCKQ7JWCRJ |
| 7.1 | @vola/client |
TCKX7RMHKF |
| 7.2 | @vola/react |
TCK9NUHWW6 |
| 8.1 | apps/examples and the compose demo profile |
TCKKR2PUDE |
| 8.2 | documentation, the release workflow, npm metadata | TCKT9JUU59 |
-
A tutorial on vol-a.com: a ticket desk on vola and memento, from an empty folder. Seven steps, in English and Serbian, written from the history of
apps/tutorial/ticket-desk; every command on the page was run as written (apps/website/scripts/tutorial.mjs). Code blocks of the site now keep their tabs, so a copied Makefile works. -
apps/website(@vola/website, private): the website and documentation, for vol-a.com. Astro with Starlight under the docs and Pagefind search; a home page of its own, dark first, in Archivo and JetBrains Mono, drawn from the product: a thumbnail going from 202 to 200, a byte ruler over a recorded206, a contact sheet of real renditions, the JSV v1 segment diagram. Every request and answer it shows is recorded (scripts/capture.mjs), every command was run, every program compiles against the workspace (scripts/check-snippets.mjs, part oftypecheck). The Reference section and the changelog page are generated fromdocs/andCHANGELOG.md, and a broken link fails the build. Not part of the Docker image. -
deploy/website/stage.shanddeploy/website/nginx/stage.vol-a.com.conf: build-and-swap of the website athttps://stage.vol-a.com/;deploy/examples/nginx/examples.stage.vol-a.com.conf: the examples stack’s vhost, now in the repository and answering its own name only. -
Documentation and release (plan 8.2):
README.mdrewritten as the front page (what vola is, the quick start againstdocker-compose.yamlwithcurl, the packages, the documents);docs/API.md— every route with method, path, scope, body, answers and error codes, theRange/HEAD/ETagrules, the202thumbnail rules, tus, shares and grants, keyrings, UDC, the examples routes, and why there is no generated OpenAPI yet;docs/ARCHITECTURE.md— packages, schema,stageUpload→finalizeUpload, the CAS layout, the worker and its five jobs, the event bus andsubscribe, encryption as a layer, transfer;docs/CRYPTO.mdcompleted with a one-page summary (§ 0), the client-side rules and the departures from the Notes model (§ 14) and an operations checklist (§ 15), readable withoutnotes-crypto-for-vola.md;docs/DEPLOYMENT.md— the image, the stack, everyVOLA_*variable with its default, the key and pepper files (generate, back up apart, rotate, “without them encrypted files are lost”), volumes, the worker, a reverse proxy, backups of the database andVOLA_STORAGE_PATHtogether, upgrades;docs/CLI.md— everyvolacommand;docs/MIGRATION-FROM-VOLA-SPP.md— old route → new route →@vola/clientmethod, the auth differences, what stays (the202rule), no data migration, the checklist for the eight consumers;docs/CONTRIBUTING.md..github/workflows/release.yml: on av*tag — versions checked against the tag, lint / typecheck / build / tests, the link check andpnpm pack --dry-run, the image to ghcr.io with provenance, a GitHub release from this file, and@vola/core,@vola/lookups,@vola/server,@vola/client,@vola/react,@vola/clipublished to npm with provenance (NPM_TOKEN).tools/check-links.mjs(every relative link and anchor of the Markdown documents; in CI),pnpm pack:dry, READMEs for@vola/core,@vola/serverand@vola/cli,repository.directory/files/exports/license/engineson every public package. -
The examples site (plan 8.1,
apps/examples,@vola/examples): a Vite + React 19 site on@vola/reactand@jsudc/react, one page per capability over a demo instance — Browse (VolaFileBrowser, live, the folder in the URL), Upload (multipart under 1 MiB, resumable above it in 256 KiB chunks with progress, cancel and resume, a drop zone, the demo’s limits), Thumbnails (every size × crop with each tile’s state, Regenerate for the202 → 200sequence), Range & streaming (<video>/<audio>on/public/:id, a Range probe that shows the206), Share (VolaShareDialog, the last link), Encrypted files (tenanton seeded files;keyringbehindVolaPinGateover the visitor’s private folder with the unlock countdown), API (the routes andcurlwith the demo key),/udc/:collection; the sidebar frommenu.yaml(themenucollection, a built-in copy without it), EN / SR, Settings (base URL, own key, instance, the visitor id with “New identity”). The visitor’s key is read-only; ademoFetchsends every write to the server’s write proxy. 48 tests. -
@vola/server: the demo routes (VOLA_EXAMPLES=true,packages/server/src/examples/):GET /examples/confighands outVOLA_DEMO_API_KEY(read-only), the demo instance, the limits and the features;ANY /examples/write/<route>replays a visitor’s write (X-User-Id: demo-…) underVOLA_DEMO_WRITE_KEYafter the policy — uploads (5 MiB, a type list enforced after the upload: a wrong type is purged and415), the resumable protocol (Locationrewritten), a visitor’s own files and folders (seeded ones403), shares (expiry capped at the TTL), the visitor’s keyring — and a per-address rate limit (429+Retry-After);POST /examples/regenerate/:fileIddrops a file’s thumbnails (StorageBackend.removeDerived); the purge removes a visitor’s keyrings (crypto-shred), files and folders afterVOLA_DEMO_TTL_HOURS(POST /examples/purgefor an admin). At startup the server creates the demo tenant and stores both keys (by hash, with their scopes), and refuses a visitor key that can write.VOLA_UI_DIRserves a built SPA at/and/en/with anindex.htmlfallback (installUi);VOLA_TRUST_PROXY. -
@vola/cli:vola demo-keys(a key pair for.env) andvola demo-seed(uploadsapps/examples/assets— ten generated files,ASSETS.md— into the demo instance over HTTP with@vola/client, an upsert per slug, media setis_global_public; the composeseeder). -
Compose / image: the image builds the site into
/app/uiand carries the demo pack;docker-compose.yamlgains the examples variables,VOLA_SECRETS_DIR(the key and pepper files at/run/secrets/vola) and theseederservice under thedemoprofile. -
E2E:
packages/e2e/test/examples.e2e.ts— the built site at/and every page,/examples/config, the seeder twice, the visitor’s key,202 → 200,206, the proxy, and a server withoutVOLA_EXAMPLES; the suite’s own server now runs with the examples on. -
@vola/react(plan 7.2): the React components an application embeds for the whole vola surface, on@jsudc/react(peer, with@jsudc/coreand@tanstack/react-query; React 19).<VolaProvider client locale="en|sr">— the client, i18n (VOLA_MESSAGES,enandsr, overridable throughmessages), the UDC providers, the keyring store with its auto-lock, and the in-memory cache of decryptedblob:URLs.<VolaFileBrowser instanceType instanceId folderPath? onOpen? columns? actions?>— breadcrumbs, subfolders (open, rename, delete, new folder) and<UdcDataView collection="files">scoped to the instance and the folder through aScopedUdcClient(everylistANDed with the scope), kept current through/udc/subscribe(useFilesLive: a cached row is patched in place, anything else refetches; reconnect with backoff), drawn by the package’stablerenderer (VolaThumbin the thumbnail column, the name as the open link, a row-actions menu: download, rename, move, delete, versions, share, visibility — each a dialog), the whole surface a drop zone.useVolaUpload()+<VolaUploadButton>/<VolaUploadList>: one multipartPOSTunderVOLA_RESUMABLE_THRESHOLD(8 MiB), the resumable protocol above it with progress, cancel and resume (the fingerprint inlocalStoragesurvives a reload), an encryption select.<VolaThumb file size crop?>: fetched with the client’s headers into a cachedblob:URL;202is a placeholder retried with backoff and never cached,failed/404placeholders, a423locks the page, a change ofprocessing_statusasks again.useVolaKeyring()(status, setup, unlock, lock, changePin, recover, reset, deletePreview, stay, the auto-lock phase) and<VolaPinGate>: six-digit PIN fields, setup with the recovery key shown once behind a “saved” checkbox,403 pin_wrongwith the attempts,429 too_many_attemptswith aretry_aftercountdown and the fields disabled,422 pin_invalidby reason, recover (a new recovery key shown once), reset with the counts, the sentence about permanence and the wordRESET;<VolaKeyringStatus>and<VolaChangePinDialog>. Auto-lock afterlockAfterMs(120 s) + a 10 s countdown with “Stay unlocked”, a slept tab locks at once, a tab hiddenawayMs(30 s) locks on return,pagehidesends the beacon; a lock revokes everyblob:URL and starts a new generation, so a late answer is dropped (BlobCache).<VolaShareDialog file>: password, expiry, most downloads, the link shown once with Copy, the note for an encrypted file (plaintext for the recipient, the secret only after#), list and revoke. Accessible dialogs (VolaModal:role,aria-modal, focus trap, Escape, overlay, focus restored) and menus (VolaMenu:menu/menuitem, arrows) without a dependency;@vola/react/styles.csson@jsudc/react’s tokens, no Tailwind in the package. 59 tests (Vitest + Testing Library against a fakefetchand a fake WebSocket), coverage ≥ 80 %.packages/react/README.mdanddocs/REACT.md. -
@vola/client(plan 7.1): the fetch SDK for every route, for Node 24+ and browsers, depending on@vola/core(and@jsudc/coreforvola.udc) only, with an injectablefetch.new VolaClient({ baseUrl, apiKey, userId?, tenantSlug?, fetch?, validate? })with the groupsfiles(upload from aFile/Blob/Uint8Array/stream — streams are framed as multipart without buffering — download as a streamingResponsewithRange/304,info,list,iterate,versions,patch,delete,purge,byPath,bySlug,putSlug,public,thumb→{status: "ready" | "generating" | "failed" | "not_modified"},thumbUrl),folders,uploads(resumable(): tus creation,HEADfor the offset,PATCHin chunks, progress,AbortSignal, a fingerprint store —localStoragein a browser, memory in Node, or injected — so an interrupted upload continues where the server stands; pluscreate,status,append,abort,protocol),shares(create/list/get/revoke, the recipient’sVolaClient.openShare(url)that turns the#<secret>fragment intoX-Share-Secret, folderlisting, andcreateCallerGrant— the caller-made grant of acallerfile, sealed with WebCrypto),keyrings(status/setup/changePin/recover/unlock/lock/close/reset/deletePreview, adminstatusOf/resetOf; the unlock token lives in the instance’s memory only,lock()ends and forgets it,withUnlock(token)derives a second instance,lockOnUnload()sends anavigator.sendBeaconto/unlock/closeonpagehide),stats,keys,admin.transfer,instanceTypes(),lookups(),live()/ready(), andudc(anUdcClienton/udcwith the same auth). Errors:VolaError {status, code, message, retryAfter?, details, requestId},VolaLockedErrorfor423,VolaIntegrityErrorfor409 vola_integrity.contentKeyis refused in a browser (caller_key_from_browser) before any request. Every answer is typed by its@vola/coreschema;validate: trueparses it.packages/client/README.mdhas an example per group and the vola-spp route → method migration table. -
@vola/core:callerGrantAad(fileId)andCONTENT_KEY_BYTES(the server’s share service uses the former). -
E2E:
packages/e2e/test/client.e2e.tsdrives the built SDK against the built server (upload,Range, a resumable upload aborted mid-PATCHand resumed, the keyring flow, a share grant opened through its fragment URL,callerfrom Node); the E2E stack now writes aVOLA_PEPPER_FILEso keyrings work there. -
Encryption at rest, part III (plan 6.3,
docs/CRYPTO.md§ 9–13).- The
callerprovider: the file key is wrapped under a 32-byte key the caller sends inX-Vola-Content-Keyon the upload and on every read (AAD<file id>:key:caller:<tenant id>,fk_ct60 B); the server keeps nothing but the wrapped key, logs nothing of it (LOG_REDACTcovers every place a library dumps request headers) and zeroes it when the response is out. Needs the new scopeencryption:caller(403otherwise); a request with anOriginheader is400 caller_key_from_browser; without the key423 vola_locked, with a wrong one409 vola_integrity;info/ lists / UDC show the real name only with the key. Share and transfer are409(a caller may hand over its ownfk_share_ct).vola tenant-set --default-encryption calleris allowed. - The resumable upload is sealed segment by segment as the bytes arrive, for
tenant,keyringandcaller(services/upload-crypto.ts): the part file is theJSVblob from byte 0, the incomplete last segment is kept sealed in<id>.partialunder a nonce that is never reused (its own prefix and a write counter inenc_state), the blob hash runs along in an exportable SHA-256 midstate (crypto/sha256.ts), the sniffing head is sealed too;HEADreports the plaintext offset, an interrupted PATCH resumes from the exact byte, nothing is read twice at completion. Every PATCH unwraps the key under the request’s material (X-Vola-Unlock/X-Vola-Content-Keyon each one).Vola-File-Idis on the201of an encrypted upload already (the id is in every AAD). A keyring policy that appears after an encrypted upload was created is422at completion. clientmode (POST /uploadswithencryption client+fk_ct[+meta_ct] pairs): the client seals theJSVblob itself against theVola-File-Idof the creation, the server checks the structure (422 client_blob_invalid), stores key and blob opaque and serves the ciphertext back as is (application/octet-stream,X-Vola-Encryption: client,Rangein ciphertext bytes). No thumbnail, OCR, share, rename (409 client_opaque) or transfer; never a tenant default;422on multipart.EncryptionModesgainsCLIENT.- Encrypted derivatives: thumbnails and OCR of encrypted files are sealed siblings under
the file key —
<blob>.enc-<file id>-thumb-<size>-<crop>(AAD<file id>:thumb:<size>: <crop>) andvola_file_metadata.ocr_ct(AAD<file id>:ocr;ocr_textstays NULL, so an encrypted file is not in the full-text search). The worker renders and OCRstenantfiles (it readsVOLA_KEY_FILE;ProcessingWorkerOptions.crypto), decrypting into memory and feedingpdftoppm/tesseractthrough stdin and stdout — nothing of the plaintext touches the disk;keyringandcallerfiles render inline in the request that holds the key (never202), and get no OCR in v1.0 (documented why)./thumbof an encrypted file needs the key (423without), answersCache-Control: no-storewith anETagof the file id, and is404 no_thumbnailabove the newVOLA_ENC_INLINE_DERIVE_MAX_BYTES(default 25 MiB). Purge and the crypto-shred remove the siblings. - The share grant:
POST /sharesof atenantorkeyringfile (the latter under the owner’sX-Vola-Unlock) wraps the file key under a 32-byte secretS(AAD<share id>:key,fk_share_ct) and answersurl = …/s/<token>#<S>;Sis never stored. The public download takesX-Share-Secret(401 share_secret_requiredwithout,409 vola_integritywrong, then the decrypted stream withRangeandno-store; password, expiry andmax_downloadsas before — a wrong secret is not a download). Revoking dropsfk_share_ct.ShareInfogainsencrypted;ShareCreatetakesfk_share_ctfor acallerfile. X-Vola-Encryption: <mode>on every download of an encrypted file;LOG_REDACTexported from@vola/serverfor hosts that embed the plugin under their own logger.- Migration
0009_encryption_iii:vola_file_metadata.ocr_ct,clientin thevola_file.encryptionCHECK.
- The
-
Encryption at rest, part II — the
keyringprovider (plan 6.2,docs/CRYPTO.md§ 8; the thilo Notes model taken as it is). A keyring belongs to one principal (X-User-Id) of one tenant (vola_keyring, migration0008_keyrings; unique per live(tenant_id, principal)) and holds a 32-byte master key twice wrapped: under Argon2id(PIN, 16 B salt, pepper as the Argon2secret; 64 MiB / t = 3 / p = 1, the parameters stored PER KEYRING inkdfso a raise needs no migration) and under a 160-bit base32 recovery key (8 × 4, shown once, typed input normalised: case, separators,0 → O,1 → I); AAD<keyring id>:mk:pin/:mk:recovery. The file key of akeyringfile is wrapped under the master key (fk_ct60 B, AAD<file id>:key:keyring:<keyring id>,vola_file.keyring_id). The pepper comes fromVOLA_PEPPER_FILE(default/run/secrets/vola.pepper; key-file format, the first line active, rotate by prepending — a keyring moves to the active line at its next unlock;vola pepper-generate,vola pepper-status). Routes under/keyrings(scopekeyrings:write,400 user_requiredwithoutX-User-Id):GET me/status(does not extend the token),POST me {pin}→201 {keyring_id, recovery_key}(409 keyring_exists,422 pin_invalid {reason: length | digits | trivial}— six digits, no all-the-same, no run),PUT me/pin(re-wraps the master key only —fk_ctand blobs untouched — and drops every token),POST me/recover {recovery_key, new_pin}→ a NEW recovery key (a wrong one is403 recovery_wrongand never counts as a PIN attempt),POST me/unlock {pin}→{token, expires_in},DELETE me/unlockand the API-key-less beacon aliasPOST me/unlock/close {token}(JSON ortext/plain),POST me/reset {confirm: "RESET"}(the crypto-shred: every file under the keyring — versions, soft-deleted rows — storage first, then the rows, then the keyring, then every token;500 blob_not_removedkeeps the rows of what failed),GET me/delete-preview; an admin key may read the status of and reset another principal (/keyrings/by-principal/:principal/…), never unlock. Unlock tokens (services/unlock.ts): 32 random bytes base64url in Redis (vola:unlock:<token>→{tenant_id, principal, keyring_id, mk}with the master key wrapped under the activeVOLA_KEY_FILEline, HKDF saltvola-unlock-kek, bound to the token; an index set per principal fordropAll), a sliding TTLVOLA_UNLOCK_TTL_S(default 150 s) refreshed by every request that carriesX-Vola-Unlock— never a URL —, and one423 vola_lockedfor every missing, expired, foreign or wrong token. Brute force: the counter andlocked_untilin the keyring row (survive a restart), a per-principal mutex (SET NX EX 15; a second check in flight is429withretry_after: 1), the Notes table (1–2 free, 3 → 1 s, 4 → 5 s, 5–9 → 30 s, 10 → 1 h, then doubling),429 too_many_attempts+Retry-Afterfor the right PIN too while locked,403 pin_wrong {attempts, retry_after}, the right PIN clears the counter. Files:encryption=keyringon an upload (multipart, slug, tus) needs the owner’s token (423before a byte is read); download,infoandPATCH {filename}of a keyring file without it are423; REST lists, UDC rows and subscriptions keep the<encrypted>mask (a subscription reveals under the token of ITS OWN upgrade, never the uploader’s —decidenow runs under the subscription’s context); another principal’s token behaves as none; akeyringfile can still not be shared, made globally public or thumbnailed, and an instance holding one is refused byPOST /admin/transferwith409 encrypted_transfer_unsupported— by design, a keyring is one person’s of one tenant. Encrypted folders are a policy:PATCH /folders/… {default_keyring: "me" | null}setsdefault_keyring_id, and every new upload into the folder or below it is a keyring file under that keyring (the uploader needs that keyring’s token; an explicit other mode is422; the folder must be named before thefilepart like theencryptionfield; versions inherit through their parent; a tus upload reads the policy at creation and completion); moving a file never touches its crypto.vola tenant-set --default-encryption keyringis allowed. Audit eventsVOLA_KEYRING_CREATED,_PIN_CHANGED,_RECOVERED,_RESET,_LOCKED_OUT(instance_type: vola_keyring, ids and counts only); logsvola_unlock_failed,vola_locked_out,vola_recovery_failedwith ids and counters; never a PIN, a recovery key, a token (a 16-hex fingerprint at most), a master key or a name. Without Redis, the pepper file or the key file the provider is503 encryption_unavailable(the start-up log saysno Redis: no keyring provider); plain andtenantfiles are unaffected.@vola/core:UNLOCK_HEADER,DEFAULT_UNLOCK_TTL_S,PIN_LENGTH, the*_CODEconstants, the keyring schemas,FolderPatchSchema.default_keyring;@vola/server:src/crypto/keyring.ts,services/keyrings.ts,services/unlock.ts,routes/keyrings.ts,KeyringWrapProvider,LockedError,EncryptionService.assertUploadable/currentUnlock/unlocks,wrapNewKey→{fkCt, keyringId},resolveMode(tenant, explicit, policyKeyringId),effectiveKeyringId(OfPath),setFolderKeyring,keyringPepperUsage,TenantContext.unlockToken,VolaPluginOptions.unlocks/keyrings,Config.pepperFile/unlockTtlS;@vola/cli:pepper-generate,pepper-status. Tests:test/keyring-crypto.test.ts(unit),test/keyrings.test.ts(a real Redis, a fake clock for the lock-out table, a dump test that re-derives MK and FK and searches every column, the blob and Redis for them). -
Encryption at rest, part I (plan 6.1,
docs/CRYPTO.md). A new crypto core (@vola/serversrc/crypto/, purenode:cryptoAES-256-GCM, no I/O): the segmented blob formatJSVv1 — a 24-byte header ("JSV", version,segment_sizeu32 — default 1 MiB, 64 KiB … 64 MiB —, 8-byte randomnonce_prefix,plaintext_lengthu64 or the “deferred” marker) and segmentsct ∥ tagwith nonceprefix ∥ iand AADheader ∥ file_id ∥ i ∥ last(∥ length on the last) — so truncation, an added or reordered segment, a changed header, an unknown version and a blob transplanted onto another file id all fail (IntegrityError), aRangedecrypts only the segments it touches, and memory is one segment per request. The plaintext length of a streamed upload is derived from the ciphertext length and authenticated by the last segment’s AAD (the header carries it when it was known, e.g. a resumable upload).createEncryptStream,createDecryptStream(reads the header and the needed span through aCiphertextSource, verifies the first segment before handing out the stream, dispatches on the version),ciphertextRangeFor,sealMeta/openMeta({filename, mime, metadata, sniffed}under the file key, AAD<file id>:meta), theWrapProviderinterface (wrap/unwrapwith lazyrewrapped, AAD<file id>:key:<mode>:<tenant id | keyring id>) and thetenantprovider:VOLA_KEY_FILE(default/run/secrets/vola.key; base64 32-byte lines, the first active), KEK = HKDF-SHA256(line, saltvola-tenant-kek, info = tenant id),fk_ct=kid(4) ∥ nonce ∥ ct ∥ tag(64 B), unwrap tries the hinted line then every line and re-wraps under the active one (lazy rotation: prepend a line, old ones retire as files are read). A missing key file never stops the server:503 encryption_unavailableon encrypted uploads, downloads andinfountil it is there (re-read on change).409 vola_integritywith the one fixed sentence “The file could not be decrypted.” for every integrity failure. Uploads (POST /files,PUT …/slug/:slug, the tus completion) takeencryption=tenantfrom theencryptionform field (before thefilepart),X-Vola-Encryption, theencryptionUpload-Metadatapair, or the tenant’s newdefault_encryption(migration0007_encryption,vola tenant-set --slug <s> --default-encryption none|tenant); the stream is plaintext → MIME sniff → encrypt → CAS, the row stores<id>.bin/application/octet-stream/other/{},encryption,enc_format = 1,fk_ct,meta_ct,size= plaintext length andhash= hash of the CIPHERTEXT (no plaintext hash anywhere, no deduplication of encrypted files, no collision rename), the upload limit is measured on the plaintext, and the plaintext part file of a resumable upload is removed once the ciphertext is committed. Downloads of an encrypted file decrypt the requested range (206in plaintext coordinates),ETag: "<file id>",Cache-Control: no-store,X-Content-Type-Options: nosniff,inlineonly for a PNG/JPEG/GIF/WebP the bytes identified, otherwiseattachment; filename*=with the decrypted name.…/info,GET /files/:type/:id,…/versions, UDCfilesrows (list, read, subscribe) show the real name, type, extension, kind and metadata when the server holds the key (filters, sorts and cursors keep the<encrypted>mask); the plugin’sdecorateRowruns after.PATCH {filename}re-seals the metadata of an encrypted file.POST /admin/transferandvola transferre-wrap the key of everytenantfile for the destination tenant inside the transaction (503without the key file,409for a key that does not open) and refuse onlykeyring/callerfiles with409 encrypted_transfer_unsupported. The worker still skips encrypted files;is_global_publicstays409 encrypted_not_public; logs and audit payloads never carry the name or type of an encrypted file. CLI:vola keys-generate [--path](0600, refuses to overwrite),vola keys-status [--path](files per key line,NO LINEwarning for keys that are gone, never a key),vola tenant-set.@vola/core:UPLOAD_ENCRYPTION_FIELD,ENCRYPTION_HEADER,INTEGRITY_ERROR_CODE/_MESSAGE,ENCRYPTION_UNAVAILABLE_CODE,ENCRYPTED_STORED_MIME,UPLOAD_META_KEYS.encryption,Tenant.default_encryption;@vola/server: everything ofsrc/crypto/,EncryptionService/createEncryptionService/tenantKeyUsage(services/encryption.ts),VolaPluginOptions.encryption,Config.keyFile,FilesDeps.crypto,describeFile(s),revealFile,StageOptions,EncryptedStage,sendEncryptedFile,ENCRYPTED_INLINE_MIMES,detectMimeDetailed,setTenantDefaultEncryption. New documentdocs/CRYPTO.md. Phase 6.2 (keyring, above) and 6.3 (caller, encrypted thumbnails/OCR, share grant, segment-wise resumable) plug into the same format and interface;calleranswers501today. -
Admin transfer and the memento audit trail (plan 5.2).
POST /admin/transfer(scopeadmin, i.e. an admin key;X-Tenant-Slugignored;{from_tenant, to_tenant, instances: [{instance_type, instance_id}], user_map?, dry_run?}) moves every row of the listed instances from one tenant to another in ONE transaction —vola_file(every version, the soft-deleted ones too),vola_folder(a path that already exists on the destination is merged into that folder: files, subfolders, share links and uploads re-pointed, the source row removed; a live source folder revives a deleted destination one),vola_share_link(tokens unchanged),vola_processing_job,vola_file_metadata, finished or expiredvola_uploadrows — then recomputes the statistics of both tenants (the source’s instance snapshots dropped, the destination’s computed) and publishespurgedon the source tenant’s event channel andcreatedon the destination’s.user_maprewritescreated_by/deleted_by/last_accessed_by(files),created_by/deleted_by(folders) andcreated_by(shares) in oneCASEper column. Answers the counts (files,folders,merged_folders,shares,jobs,metadata,uploads,instances,dry_run); idempotent (a repeat reports zeros);dry_runruns the same statements and rolls them back. Refusals before anything is written:404 tenant_not_found(the destination must exist — vola-spp created it; this port does not),409 encrypted_transfer_unsupportedfor an instance holding anencryption != nonefile (the TODO for phase 6.1 TCKK5UTHJX, thetenantre-wrap, is inservices/transfer.ts),409 uploads_in_progressfor a resumable upload still running (it is refused rather than moved: the client resuming it holds a source-tenant key). CLIvola transfer --from <slug> --to <slug> --instance type:id [--instance …] [--user-map file.json] [--dry-run](announces the move through Redis whenVOLA_REDIS_URLis set). Audit (decision 13): withVOLA_MEMENTO_URL+VOLA_MEMENTO_API_KEY(new, both or neither) the operationsVOLA_FILE_DELETED(soft delete, every file of a recursive folder delete),VOLA_FILE_PURGED,VOLA_FILE_VISIBILITY_CHANGED,VOLA_SHARE_CREATED,VOLA_SHARE_REVOKED,VOLA_KEY_CREATED,VOLA_KEY_REVOKED(API and CLI) andVOLA_INSTANCES_TRANSFERREDare pushed to<url>/eventsas memento events (instance_typevola_file/vola_share/vola_key/vola_tenant,actor_id=X-User-Idorkey:<prefix…last4>,cli:<user>from the CLI; payloads of ids, size, MIME, kind and tenant slug — never a token, password, key, nor thefilenameof an encrypted file). Delivery: anauditBullMQ job (5 tries, exponential backoff; a4xxother than 408/429 is dropped at once) the worker pushes when Redis is configured, one direct fire-and-forget push with a 2 s timeout otherwise; a request never waits for memento and never fails because of it; without the variables one INFO line and nothing else. The worker takes the same two variables.TenantContextgainsapiKeyLabel(vola_live…k3Qz).@vola/core:TransferRequestSchema,TransferResultSchema,TransferInstanceSchema,TRANSFER_MAX_INSTANCES;@vola/server:services/transfer.ts(transferInstances,mapUsers,distinctInstances),adminRoutes,audit/memento.ts(AuditSink,MementoSink,NoopSink,AuditDeliveryError,fileAuditPayload),audit/log.ts(AuditLog,actorOf,createAuditSink,disabledAuditLog),AUDIT_JOB,AUDIT_MAX_ATTEMPTS,ProcessingQueue.enqueueAudit,ProcessingWorkerOptions.audit,VolaPluginOptions.audit,keyAuditPayload,shareAuditPayload;@vola/cli:transfer,readUserMap,transferLines,CliOptions.audit/actor/redisUrl. New documentdocs/AUDIT.md(events, payloads, the memento-side vocabulary and template lines). -
Share links and statistics (plan 5.1). New table
vola_share_link(migration0006_shares_stats:tenant_id,file_idXORfolder_id(CHECK),token_hash— the SHA-256 of a 32-byte base64url token, unique —scope(ShareScopes, v1PUBLIC_LINKonly),password_hash(argon2id, 19 MiB / t=2 / p=1),expires_at,max_downloads,download_count,created_by,created_at,revoked_at, andfk_share_ctbytea reserved for the share grant of phase 6.3).POST /shares(shares:write;{file_id | folder: {instance_type, instance_id, path}, password?, expires_at?, max_downloads?, scope?}) answers201with the token (this once) and the publicurl(built onVOLA_PUBLIC_URL, new, optional, or the request’s origin); a scope other thanPUBLIC_LINKis501 not_implemented, an encrypted file409 encrypted_share_requires_grant.GET /shares[?file_id=|folder_id=][&include_revoked=1],GET /shares/:id,DELETE /shares/:id(revoke, idempotent). AnonymousGET|HEAD /s/:token(file: the download withRange/ETag/Content-Disposition; folder: a one-level JSON listing with paths relative to the shared folder) andGET|HEAD /s/:token/path/*(a file or subfolder inside a shared folder, never outside it). Password inX-Share-Passwordor?password=; missing or wrong →401 share_password_required, ten wrong ones per token in fifteen minutes →429 too_many_password_attempts(counter in Redis when configured, in memory otherwise); unknown token404 share_not_found; revoked or expired410 share_gone. Only a request that starts a download counts againstmax_downloads(GETwithoutRangeor from byte 0; atomicUPDATE … WHERE download_count < max_downloads RETURNING);HEADandRangecontinuations never count and still answer once the limit is reached, so the last granted download can be resumed; starting another is410. Share answers carryCache-Control: private, no-storeandX-Robots-Tag: noindex, nofollow; an encrypted file inside a shared folder is invisible. New tablevola_tenant_stats(same migration): one snapshot per(tenant, scope tenant|instance, instance_type, instance_id)withtotal_files,total_bytes,by_kindjsonb,oldest_at,newest_at,computed_at.GET /stats/tenant[?recompute=1],GET /stats/instance/:type/:id[?recompute=1](files:read; computed lazily on the first read, soft-deleted files never counted) andGET /stats/storage(files:read; the tenant’s live files, logical bytes, distinct blobs and their bytes; an admin key addsphysical—blobs,derived,uploadson disk — and withoutX-Tenant-Slugmeasures the whole deployment). The worker gains the repeatablerefresh-statsjob (scheduled by the server every halfVOLA_STATS_TTL_MIN, new, default 60): snapshots older than the TTL whose tenant had file activity since are recomputed; without a worker a read past the TTL recomputes instead.@vola/core:SHARE_SCOPES,ShareCreateSchema,ShareInfoSchema,ShareCreatedSchema,SharedFolderListingSchema,SHARE_PASSWORD_HEADER,TenantStatsSchema,StorageStatsSchema,RECOMPUTE_QUERY;@vola/server:services/shares.ts,services/share-password.ts(MemorySharePasswordLimiter,RedisSharePasswordLimiter),services/stats.ts,shareRoutes,sharePublicRoutes,statsRoutes,StorageBackend.usage(),ProcessingQueue.scheduleStatsRefresh,REFRESH_STATS_JOB. New dependency:argon2. -
OCR (plan 4.2). After every upload of a raster image (not SVG, not GIF) or a PDF with
encryption = nonethe server also queues oneOCRjob (VOLA_OCR_ENABLED=auto/1/0); the worker runs the systemtesseract—tesseract <file> stdout -l <langs>for an image,pdftoppm -r 200 -pnginto a temporary directory and tesseract per page for a PDF (at mostVOLA_OCR_MAX_PAGES= 20 pages, the texts joined with\f), the tools spawned with an argument list and no shell,VOLA_OCR_TIMEOUT_S(120) per page, stdout capped at 10 MiB, the temporary directory always removed — with the languages ofVOLA_OCR_LANGS(eng+srp+deu, from theOcrLanguagesvocabulary; an unknown or uninstalled one is a clear error at start). Inautomode the worker probestesseract --versionat its start and skips the jobs (SKIPPED, one WARN line) when it is missing; with1it refuses to start. New tablevola_file_metadata(migration0005_file_metadata:file_idPK →vola_filecascade,tenant_id,ocr_text,ocr_lang,ocr_pages,ocr_at,ocr_tsv— a storedtsvectorgenerated from the text with thesimpleconfiguration, GIN-indexed).GET …/:fileId/infogainsocr: {status, lang, pages, text_preview}(the first 500 characters;?ocr=fulladdstext). The UDCfilescollection gainsocr: yes/no in the row and the view’s “OCR” column, and as a filtercontains <words>is a full-text search (plainto_tsquery('simple', …)overocr_tsv),eq true|false/is_null/is_not_nullthe flag; a livesubscribewith such a filter is matched in SQL, so the row arrives when its text is in. The worker publishes aprocessingevent after every OCR job.@vola/core:OCR_LANGUAGES,parseOcrLangs,ocrSupported,isOcrEligible,OcrInfoSchema,FileDetailSchema,OCR_TEXT_PREVIEW_LENGTH,OCR_PAGE_SEPARATOR;@vola/server:services/ocr.ts(runCapped,probeTesseract,extractText,saveOcrResult,ocrInfoOf),OCR_JOB,JobDispatcher.requestOcr,ProcessingWorker.ocrAvailability(). CI installstesseract-ocr(eng, srp, deu). -
Background jobs and thumbnails (plan 4.1).
@vola/servergains a second process, the worker (node dist/worker.js,pnpm start:worker, thevola-workercompose service on the same image), consuming the BullMQ queuevola-processingonVOLA_REDIS_URLwithVOLA_WORKER_CONCURRENCY(2) jobs at once and a graceful SIGTERM;VOLA_QUEUE_PREFIX(vola) namespaces the Redis keys.VOLA_WORKER_ENABLED=auto(default: async when Redis is set) /1(insist; one ERROR line and synchronous work without Redis) /0(always synchronous — thumbnails render inline on/thumb, OCR will not run; one INFO line per process, never an error). New tablevola_processing_job(migration0004_processing_jobs:id,tenant_id,file_id,kind,params,status,attempts,error,created_at,started_at,finished_at;(file_id, kind, params)unique) andprocessing_statuson every file info, the UDCfilesrow and…/info: the worst status of the file’s jobs wins (FAILED>RUNNING>PENDING>DONE,SKIPPEDignored,nullwithout jobs). After every upload (plain, slug, version, resumable) of a raster image (not SVG) or PDF withencryption = none, fourTHUMBNAILjobs (64 / 128 / 256 / 512, cropcover) are queued; the worker renders them withsharp(rotate()for EXIF,cover= centre crop,fit= contain,attention, WebP quality 80; a PDF’s first page throughpdftoppm -f 1 -l 1 -r 72 -png), 30 s per job, 3 tries thenFAILEDwith a shorterror, and stores each as the derived filethumb-<size>-<crop>.webpnext to the blob (shared across tenants, purged with it); after every job aprocessingevent goes out, so a livefileslist updates.GET|HEAD /files/:type/:id/:fileId/thumb/:size?crop=(files:read):400 invalid_size/invalid_crop;200+X-Thumbnail-Status: ready+Cache-Control: private, max-age=86400ETag/304when the rendition exists;202+ a grey WebP placeholder (~50 B) +X-Thumbnail-Status: generating+Cache-Control: no-cachewhen it does not and the worker is on (the job row is written or refreshed); inline rendering and200without a worker (or when the queue cannot be reached);200placeholder +X-Thumbnail-Status: failedfor a file that cannot be rendered;404 no_thumbnailfor an unsupported type or an encrypted file. The expired-upload sweep moved to a repeatable BullMQ job in async mode (the in-process timer stays for deployments without a worker).@vola/core:PROCESSING_KINDS,PROCESSING_STATUSES,aggregateProcessingStatus,THUMBNAIL_SIZES,THUMBNAIL_CROPS,thumbnailDerivedName,thumbnailSupported,THUMBNAIL_STATUS_HEADER. New dependencies:bullmq,sharp,pino. The E2E stack starts the built worker next to the built server.
-
Real-time
subscribe(plan 3.2):GET /udc/subscribeupgrades to a WebSocket (bearer.<key>subprotocol next tovola.v1, or the usual headers;files:read; refusals are plain401/403/400before the upgrade; the key is never read from the URL). A client sendsudc.subscribe {collection: "files", filter}with alist-style filter (top-levelinstance_typerequired,instance_id,folder_path,include_deletedand the rest as inlist; up to 32 per connection) and receivesudc.row.upsert(the row aslistanswers it, read back under the tenant and the same masking /decorateRow) orudc.row.remove(an id) whenever a file of that instance is uploaded, replaced by slug, versioned, completed by a resumable upload, moved, renamed, made (in)visible, soft-deleted, purged, or moved by a folder rename / deleted with a folder.FileEventBus(@vola/server): every writer publishes{tenantId, instanceType, instanceId, folderId, fileId, kind}after its commit — Redis pub/sub onvola:files:<tenant id>withVOLA_REDIS_URL(several server and worker processes), in-process without;publishProcessingStatusis the hook for the plan-4.1 worker. Heartbeat (VOLA_WS_HEARTBEAT_MS), slow-consumer close4008(VOLA_WS_MAX_BUFFERED),1001on shutdown,1011when the feed is down.volaPlugintakeseventsandsubscribe(falseswitches either off);@fastify/websocketis registered unless the host did. Wire schemas in@vola/core(ClientMessageSchema,ServerMessageSchema,SUBSCRIBE_CLOSE_CODES,FILE_EVENT_KINDS). Thefilescollection now reportscapabilities.subscribe: true. Docs:docs/REALTIME.md. -
Lookups, translations and the UDC
filescollection (plan 3.1).@vola/lookupsis now the full copy of@memento/lookups(YAML compiler and registry, CSV translations with a validator, candidate recorder, codegen) pluspromoteCandidates;lookups.yaml(FileKinds,ProcessingStatuses,ProcessingKinds,ShareScopes,OcrLanguages,EncryptionModes— noInstanceTypes) andi18n/translations.csv(en, sr) live at the repository root.GET /lookups?locale=en|sr(no key; fallback en) serves terms, wire values and labels;GET /instance-types(files:read) the tenant’s instance types with live-file counts. An upload whosekind/encryptionthe vocabulary does not know is recorded undervar/candidates(VOLA_LOOKUPS_PATH,VOLA_TRANSLATIONS_PATH,VOLA_RECORD_CANDIDATES,VOLA_CANDIDATES_DIR);vola lookup-promote,vola lookups validate|candidatesmanage the queue.@jsudc/server0.2.1 is mounted under/udcbehind the API-key auth (in-protocol refusals,files:readto read, admin withX-Tenant-Slug) with the read-onlyfilescollection (udc/files/view.yaml): required top-levelinstance_typefilter (empty list without it), optionalinstance_id,folder_path(one level,""root),filename(ilike),mime_type,extension,kind,size,created_at,include_deleted; sort bycreated_at/filename/size; keyset cursor paging withidtiebreak and exacttotal;download_url/thumb_urlin rows; an encrypted row is masked (<encrypted>, no MIME/extension) in rows, filters, sorts and cursors, with adecorateRowhook for phase 6.menu.yamlis served as themenucollection (VOLA_MENU_PATH). The Docker image ships the vocabulary and menu under/app/config. -
Resumable uploads (
vola_upload, migration0003_uploads):OPTIONS|POST /uploads,HEAD|PATCH|DELETE /uploads/:idspeaking tus 1.0 core +creation,termination,expiration, implemented natively in@vola/server(no@tus/server) sotus-js-clientworks unchanged — verified by an e2e test that uses it.Upload-Metadatacarriesinstance_type,instance_id,filename(required),folder_path,parent_id,slug,content_type/filetype,metadata;Upload-Lengthis required (Upload-Defer-Length→400, overVOLA_MAX_UPLOAD_BYTES→413). Partial bytes go toVOLA_STORAGE_PATH/uploads/<id>.partas they stream, the offset is committed only afterfsync, a parallel PATCH is409 upload_locked(FOR UPDATE NOWAIT), a wrong offset409 upload_offset_mismatch, a client cut mid-body keeps what arrived. Completion goes through the samefinalizeUploadasPOST /files(hash, dedup, MIME, rename, folder, version, slug); the last PATCH and every later HEAD carryVola-File-Id. An upload belongs to the tenant, not the key.VOLA_UPLOAD_TTL_HOURS(24): expired uploads are swept by a periodic job in the server process.@vola/coregains the tus header names and theUpload-Metadatacodec (encodeTusMetadata/decodeTusMetadata). -
Folders, versions and visibility (
vola_folder, migration0002_folders): virtual folders inside an instance (POST|GET|PATCH|DELETE /folders/:type/:id/*path— chain auto-create, one-level listing, rename and move with every descendant path rewritten in one transaction, recursive soft delete,409 folder_exists/folder_not_empty), paths of 1–255-character segments (no/,\, control characters,.or..; 32 levels), uploads withfolder_path/folder_id,GET|HEAD …/path/*,PATCH …/:fileId(move, rename with409 file_exists,is_public,is_global_public), versions throughparent_id(GET …/:fileId/versions, purge of the whole chain),is_publicreadable by any authenticated tenant, and the anonymousGET|HEAD /public/:fileIdforis_global_publicfiles (Cache-Control: public, max-age=300; never an encrypted file —409 encrypted_not_public).vola_file.folder_idandparent_idare foreign keys now. -
Files (
vola_file, migration0001_files): content-addressable storage on disk (StorageBackend/FilesystemBackend:blobs/aa/bb/cc/<sha256>, streamed throughtmp/with SHA-256 on the fly, fsync, atomic link, dedup, derived files next to the blob, path-traversal safe),POST /files/:type/:id(streaming multipart,413 file_too_largeoverVOLA_MAX_UPLOAD_BYTES, MIME from magic bytes → extension → declared type,kind, collision renamea (1).pdf),PUT …/slug/:slug(upsert),GET|HEAD …/:fileIdand…/slug/:slug(Range/206/416,ETag/304,Content-Dispositionwith RFC 5987 names,nosniff,?download=1,last_accessed_*),GET …/:fileId/info, cursor list, soft delete and purge (blob removed only when no row of any tenant references it). The encryption columns (encryption,enc_format,keyring_id,fk_ct,meta_ct) are declared now and staynone/NULL until phase 6. -
Tenants and API keys (
vola_tenant,vola_apikey, migration0000_tenant_apikey): keys arevola_live_…/vola_test_…/vola_admin_…(32 base62 characters), only their SHA-256 is stored, the plaintext is shown once. Scopesfiles:read,files:write,folders:read,folders:write,shares:write,keys:write,keyrings:write,admin. -
@vola/server: API-key auth on every route (Authorization: Bearer,X-Api-Key, or thebearer.<key>WebSocket subprotocol),TenantContextonrequest.volaand throughrequireTenant()(AsyncLocalStorage), routeconfig.scope/config.auth = "none"/config.tenant = "optional", admin keys selecting a tenant withX-Tenant-Slug,X-User-Idas the principal,last_used_atwritten at most once a minute per key.POST|GET /keys,DELETE /keys/:id(scopekeys:write). -
@vola/cli:vola migrate,create-tenant,create-key,create-admin-key,list-keys,revoke-key(--jsonfor machine output). -
Monorepo scaffold (pnpm workspaces, Turborepo, Biome, Vitest, TypeScript 5.9, Node 24):
@vola/core,@vola/lookups,@vola/server,@vola/cli,@vola/client,@vola/reactand the private@vola/e2esuite. -
@vola/server:volaPlugin(Fastify 5) mounted underVOLA_PREFIX(default/vola), Zod-validatedVOLA_*configuration,GET /health/liveandGET /health/ready(PostgreSQL, and Redis when configured),X-Request-IDecho/generation, the{ error: { code, message } }error envelope, Drizzle migrations (pnpm db:migrate). -
compose.yaml(PostgreSQL 16 + Redis 7 for development, with thevola_testdatabase),docker-compose.yaml(thevolaimage + PostgreSQL + Redis), multi-stageDockerfilewith libvips, poppler-utils and tesseract (eng, srp, deu), GitHub Actions CI.
Changed
Section titled “Changed”- The examples stack moved to
/home/digital/sites/examples.stage.vol-a.comand is reached only athttps://examples.stage.vol-a.com/;docs/EXAMPLES-SITE.mdhas the real stage procedure, includingCOMPOSE_PROJECT_NAMEon a shared machine and what rootless podman needs, anddocs/DEPLOYMENT.mdhas a chapter on the website. 409 encrypted_share_requires_grantnow only forcaller(withoutfk_share_ct) andclientfiles;/thumbno longer answers404for encrypted files the request can open;isOcrEligibleandthumbnailableare true fortenantfiles;TENANT_DEFAULT_ENCRYPTIONSincludescaller;TenantContextgainedcontentKeyandbrowserOrigin;parseModetakes{client};EncryptedStage.fkis nullable (client).
- The audit trail reaches memento.
POST <VOLA_MEMENTO_URL>/eventscarried a top-levelactor_type, a field memento’s strictEventCreaterefuses with a422, so every audit event was dropped after one try with a WARN line. The kind of actor now travels aspayload.actor_type.docs/AUDIT.md: its template lines are Handlebars now; memento refused the old syntax with a parse error. - Examples write proxy: a visitor can only change what that visitor made. It only refused
seeded rows, so any
X-User-Id: demo-…could rename, delete or purge another visitor’s file or folder, and list, read or revoke their shares.created_bymust now equalX-User-Id, else403 demo_forbidden;GET shareslists the visitor’s own. The same goes for the ways round it: an upload’sparent_id(a planted version let a purge take a seeded file’s whole chain), a resumable upload’sslug(completing it replaced the file of that slug, the pack’s are public), another visitor’s resumable upload, and an own folder holding someone else’s rows.X-User-Idis self-declared, so this stops accidents and casual edits, not an attacker (docs/EXAMPLES-SITE.md). - The examples site’s Share page: Open in a new tab and the
curlof an encrypted file’s link answered401 share_secret_required, since a tab never sends the part after#. Both now sendX-Share-Secret, and the page says what a recipient needs. - Docs that disagreed with themselves or the code: the examples routes’ auth, the disk and Redis
rows of
CRYPTO.md§ 5 and § 8.7, an encrypted thumbnail’sETag, which files get OCR, the job timeouts, the demo’s type list (Markdown), and what the purge goes by (each row’screated_at). The quick starts poll/vola/health/ready:up --waitfails on podman.
v1.1.0released built 402bea0