@serve.zone/corestore

Corestore is the node-local storage provider for serve.zone workloads. One process starts a SmartDB database endpoint, one SmartStorage S3-compatible endpoint per configured object-storage pool, a Coreflow-facing control API, and a Docker VolumeDriver plugin. Its versioned storage API reconciles backend-neutral named filesystem and object-storage bindings.

Issue Reporting and Security

For reporting bugs, issues, or security vulnerabilities, please visit community.foss.global/. This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a code.foss.global/ account to submit Pull Requests directly.

What It Provides

Corestore packages the storage primitives that a workload usually needs on a serve.zone node:

• Database: @push.rocks/smartdb is the database server and exposes the MongoDB wire protocol on port 27017.
• Object storage: @push.rocks/smartstorage exposes one S3-compatible endpoint per physical pool; the default local pool uses port 9000.
• Control API: HTTP JSON API on port 3000 for named storage reconciliation, service-resource provisioning, metrics, snapshots, restores, and archive object replication.
• Docker volumes: Docker's VolumeDriver API over /run/docker/plugins/corestore.sock.
• Backups: @serve.zone/containerarchive stores deduplicated volume snapshots under the Corestore data directory.

Corestore is deliberately node-local. Volume data lives on the node where Docker mounts it, and the Docker driver reports Scope: local.

Runtime Layout

Default data root:

/data/corestore

Inside that root Corestore creates:

Path	Purpose
smartdb/	SmartDB file storage, user data, and the SmartData-authoritative binding and database-mutation registries.
smartstorage/	S3-compatible object data.
volumes/	Docker volume mountpoints.
volume-archive/	ContainerArchive repository for volume snapshots.
restore-staging/	Bounded archive objects staged for isolated restores.
restore-control-locks/	Durable isolated-restore lease and fencing records.
restore-control-state/	Durable isolated-restore state and mutation receipts.
resource-mutation-locks/	Per-target resource fencing records.
resource-mutation-state/	Durable target-resource mutation state.
corestore-manifest.json	Service-resource, volume, and snapshot manifest. It is not authoritative for named storage bindings.
corestore-secret.json	Persisted master secret and derived admin credentials.

The master secret is generated on first start unless CORESTORE_MASTER_SECRET is provided. Database tenant credentials are derived from the service id; named object-storage credentials are derived independently from each stable binding id and are never persisted in binding records.

Configuration

Env var	Default	Purpose
CORESTORE_DATA_DIR	/data/corestore	Persistent data root.
CORESTORE_BIND_ADDRESS	0.0.0.0	Bind address for control, S3, and DB endpoints.
CORESTORE_PUBLIC_HOST	corestore	Hostname written into generated service credentials.
CORESTORE_CONTROL_PORT	3000	Control API port.
CORESTORE_S3_PORT	9000	S3 endpoint port.
CORESTORE_OBJECT_STORAGE_POOLS_JSON	unset	Strict versioned JSON for additional local or host-mounted NFS object-storage pools.
CORESTORE_DB_PORT	27017	SmartDB MongoDB-wire endpoint port.
CORESTORE_REGION	us-east-1	Region value for S3 credentials.
CORESTORE_API_TOKEN	unset	Required 32–4096 byte control token; configure this or CORESTORE_API_TOKEN_FILE, never both.
CORESTORE_API_TOKEN_FILE	unset	Alternative file containing the control token, with one optional trailing newline.
CORESTORE_RESTORE_GRANT_KEYRING_FILE	unset	JSON keyring containing trusted RSA public keys for isolated-restore grants.
CORESTORE_RESTORE_GRANT_ISSUER	unset	Exact expected iss claim for isolated-restore grants.
CORESTORE_RESTORE_GRANT_AUDIENCE	unset	Exact expected aud claim for isolated-restore grants.
CORESTORE_CLUSTER_ID	unset	Cluster identity to which isolated-restore grants must be bound.
CORESTORE_NODE_NAME	unset	Node identity to which isolated-restore grants must be bound.
CORESTORE_ISOLATED_RESTORE_LEASE_MS	3600000	Durable restore/resource mutation lease duration in milliseconds.
CORESTORE_MASTER_SECRET	generated and persisted	Seed for deterministic tenant credentials.
CORESTORE_DB_ROOT_USER	corestore_root	SmartDB root username.
CORESTORE_DB_ROOT_PASSWORD	derived or persisted	SmartDB root password override.
CORESTORE_S3_ADMIN_ACCESS_KEY_ID	derived or persisted	SmartStorage admin access key override.
CORESTORE_S3_ADMIN_SECRET_ACCESS_KEY	derived or persisted	SmartStorage admin secret override.
CORESTORE_VOLUME_PLUGIN_SOCKET	/run/docker/plugins/corestore.sock	Docker VolumeDriver socket path.
CORESTORE_ARCHIVE_PASSPHRASE	unset	Optional ContainerArchive encryption passphrase.
CORESTORE_VERBOSE	false	Enables verbose SmartStorage logging when set to true.

Corestore refuses to start unless exactly one control-token source is configured. Tokens must contain no whitespace. The file form must be a regular, non-symlink file and is preferable when the orchestrator can mount secrets. Every TCP control API endpoint except GET /health requires exactly one Authorization: Bearer <token> header; the legacy x-corestore-token header is rejected.

The five isolated-restore settings must be configured together to enable signed restore grants. Partial configuration prevents startup; leaving all five unset keeps ordinary Corestore APIs available but makes isolated-restore operations unavailable. The keyring has this versioned shape:

{
  "version": 1,
  "keys": [
    {
      "kid": "restore-key-1",
      "publicPem": "-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----\n"
    }
  ]
}

Object-storage pools

The implicit default pool preserves the existing local SmartStorage identity at <CORESTORE_DATA_DIR>/smartstorage and CORESTORE_S3_PORT. Additional pools are configured by CORESTORE_OBJECT_STORAGE_POOLS_JSON. Each pool has a unique endpoint, physical root, backend identity, and one or more portable policy classes. Corestore starts and reconciles one SmartStorage provider per pool.

Example host-mounted NFS capacity pool:

{
  "schemaVersion": 1,
  "pools": [
    {
      "id": "archive-hdd",
      "port": 9001,
      "directory": "/storage-pools/archive-hdd",
      "backend": {
        "kind": "mountedFs",
        "expectedFilesystemType": "nfs",
        "expectedSource": "192.0.2.10:/volume1/onebox"
      },
      "classes": [
        {
          "classId": "onebox.object-storage.capacity.v1",
          "revision": "1",
          "kind": "objectStorage",
          "performanceTiers": ["capacity"],
          "durabilities": ["persistent"],
          "topologies": ["singleNode"],
          "hardQuota": false,
          "snapshotModes": ["none"],
          "backup": false,
          "encryptedInTransit": false,
          "accessModes": ["readWrite"],
          "versioning": false,
          "retention": true
        }
      ]
    }
  ]
}

The host must mount NFS before Corestore starts and bind-mount the exact mount root into the Corestore container at the configured directory. Corestore does not mount remote filesystems itself. Mounted pools require an exact numeric IPv4 server:/absolute/export source and the Linux nosymfollow VFS option. NFS server-coordinated locking must remain enabled: nolock and local_lock=all|flock are rejected, while an absent local_lock option, local_lock=none, or local_lock=posix is accepted. SmartStorage validates the mount type, source, mountpoint, remote locking, symlink policy, and publication primitives before accepting traffic. A missing, replaced, or mismatched mount fails startup instead of writing into the underlying local directory.

Pool ids, ports, directories, class revisions, and backend identities are persisted as an immutable catalog. Once a pool is adopted, its definition cannot be changed or removed, even when no live binding currently refers to it; adding a class revision to that existing pool also changes its immutable identity and is rejected. Add a new pool containing the new class revision and use the fenced migration protocol when physical placement must change.

Starting Corestore

pnpm install
pnpm build
pnpm start

For TypeScript development:

pnpm run startTs

Programmatic startup:

import { CoreStore } from '@serve.zone/corestore';

const corestore = new CoreStore({
  dataDir: '/var/lib/serve.zone/corestore',
  apiTokenFile: '/run/secrets/corestore-api-token',
  restoreGrantKeyringFile: '/run/secrets/corestore-restore-keyring.json',
  restoreGrantIssuer: 'https://cloudly.example',
  restoreGrantAudience: 'corestore.restore',
  clusterId: 'cluster-1',
  nodeName: 'node-1',
});

await corestore.start();

Offline MongoDB-wire migration

The image includes one explicit operator migration that copies a stopped workload's database from a MongoDB-wire-compatible source into Corestore's SmartDB backend. The migration is not part of normal startup. First provision the target through Corestore's normal database resource API while Corestore is running, but do not deliver its credentials to the workload. Then stop Corestore and fence every source writer. The migration requires that exact SmartDB tenant and its already-durable manifest entry, reads the manifest without rewriting it, replaces an empty target or resumes an exact replay behind SmartDB's durable publication hold, releases publication, and verifies canonical BSON documents and complete index definitions. The source database may contain no collections. The migration persists through Corestore's normal SmartData database-mutation coordinator, so provision, migration, later snapshot/restore, and deprovision remain in one durable fence lineage. An exact replay with the same migration id and fencing token returns the same released result.

The migration rejects collection options and index kinds or options that SmartDB cannot enforce. It also fails closed above a 96 MiB serialized export, 10,000 collections, 1,000,000 documents, or 100,000 indexes. Fix and release a missing SmartDB capability before retrying; split a larger migration through an explicitly reviewed process instead of weakening this preflight.

If the running Corestore uses CORESTORE_CLUSTER_ID and CORESTORE_NODE_NAME, the offline migration requires those same values so its SmartDB fence remains in the existing resource-mutation scope. Configure both or neither.

CORESTORE_MIGRATION_SOURCE_FENCED=true \
CORESTORE_MIGRATION_CORESTORE_STOPPED=true \
CORESTORE_MIGRATION_TARGET_CREDENTIALS_UNDELIVERED=true \
CORESTORE_MIGRATION_SOURCE_MONGODB_URI='<protected MongoDB URI>' \
CORESTORE_MIGRATION_SOURCE_DATABASE='<source database>' \
CORESTORE_MIGRATION_SERVICE_ID='<stable service id>' \
CORESTORE_MIGRATION_SERVICE_NAME='<service name>' \
CORESTORE_MIGRATION_ID='<stable migration id>' \
CORESTORE_MIGRATION_FENCING_TOKEN='<positive integer>' \
pnpm run migrate:legacy-mongodb-to-smartdb

CORESTORE_DATA_DIR, CORESTORE_PUBLIC_HOST, and CORESTORE_DB_PORT select the target Corestore instance and keep their normal defaults. Never place the source URI in logs or committed configuration.

Control API

GET /health is always unauthenticated:

curl http://corestore:3000/health

All other control endpoints require exactly one Authorization: Bearer <token> header.

Useful endpoints:

Method	Path	Purpose
GET	/health/details	Returns authenticated component-level health details.
GET	/metrics	Returns database, object storage, and volume metrics.
GET	/control/v2/storage/capabilities	Advertises enforced portable storage guarantees and exact policy revisions.
POST	/control/v2/storage/bindings/reconcile	Idempotently reconciles one stable named binding.
GET	/control/v2/storage/bindings?serviceId=<id>	Lists canonical secret-free bindings for a service.
GET	/control/v2/storage/bindings/<id>	Gets one canonical secret-free binding.
POST	/control/v2/storage/bindings/<id>/credentials	Returns object-storage credential material to the authenticated adapter with Cache-Control: no-store.
POST	/control/v2/storage/bindings/<id>/release	Applies the binding's declared retain/delete policy and persists a tombstone.
GET	/control/v2/storage/bindings/<id>/migration-snapshot	Captures the exact unfenced source binding snapshot required to prepare a migration.
POST	/control/v2/storage/migrations/prepare	Fences the source and prepares a hidden destination binding on a different pool.
GET	/control/v2/storage/migrations/<id>	Returns the durable migration phase and required consumer action.
POST	/control/v2/storage/migrations/<id>/quiesce	Accepts bound quiesce evidence, seals the source, verifies the destination, and performs the durable cutover.
POST	/control/v2/storage/migrations/<id>/activation	Accepts bound evidence that the consumer started on the destination.
POST	/control/v2/storage/migrations/<id>/cleanup	Performs fenced source cleanup after destination activation.
POST	/control/v2/storage/migrations/<id>/abort	Aborts a pre-cutover migration through the versioned recovery contract.
POST	/control/v2/storage/migrations/<id>/resume	Resumes a retryable phase without bypassing its durable fence.
GET	/volumes	Lists managed Docker volumes.
GET	/volumes/snapshots?name=<volume>	Lists snapshots for one volume or all volumes.
POST	/volumes/create	Creates or updates a named managed volume.
POST	/volumes/remove	Removes an unmounted volume.
POST	/volumes/snapshot	Creates a ContainerArchive snapshot of a volume.
POST	/volumes/restore	Restores a snapshot into a volume.
GET	/resources	Lists provisioned per-service DB/S3 resources.
POST	/resources/provision	Provisions database and/or object storage for a service.
POST	/resources/deprovision	Deletes provisioned DB/S3 resources for a service.
POST	/resources/database/digest	Computes a bounded canonical content digest for exactly one service-owned SmartDB database.
POST	/resources/database/export	Exports exactly one service-owned SmartDB database as a bounded portable payload.
POST	/resources/database/import	Replaces a pre-provisioned service database under a durable fence and returns a held-publication receipt.
POST	/resources/database/import/commit	Releases the exact held database only after the orchestrator durably records its receipt.
POST	/resources/database/backup/export	Streams one selected service database as a bounded portable ContainerArchive closure.
POST	/resources/database/backup/restore	Verifies a selected closure in isolated staging and durably restores it into a pre-provisioned target database.
POST	/resources/snapshot	Snapshots service DB/S3 resources.
POST	/resources/restore	Restores service DB/S3 resources.
POST	/archive/manifest	Returns a manifest for the local archive repository.
POST	/archive/object/read	Reads an archive object as base64 with size and SHA-256.
POST	/archive/object/write	Writes a validated archive object from base64.
POST	/archive/prune	Prunes archive data under configured retention and free-space bounds.
POST	/isolated-restore/prepare	Validates an operation-scoped grant, mappings, and archive manifest, then creates durable fenced state.
POST	/isolated-restore/archive/object/write	Writes one bounded archive object chunk under a write-object grant.
POST	/isolated-restore/execute	Restores only the grant-authorized scratch resources.
POST	/isolated-restore/status	Returns sanitized durable progress under a status grant.
POST	/isolated-restore/cleanup	Cleans staged artifacts under a cleanup grant while preserving durable fencing evidence.

Provision resources for a service:

curl -X POST http://corestore:3000/resources/provision \
  -H 'content-type: application/json' \
  -H 'authorization: Bearer <CORESTORE_API_TOKEN>' \
  -d '{"serviceId":"svc-123","serviceName":"api","capabilities":["database","objectstorage"]}'

The response includes service-specific environment variables such as MONGODB_URI, S3_BUCKET, AWS_ACCESS_KEY_ID, and AWS_ENDPOINT_URL.

MONGODB_URI, MONGODB_URL, and the related MONGO_* names are intentional: SmartDB is the database server, and workloads connect to it through the MongoDB wire protocol. They do not imply that a MongoDB server is running.

Portable database handoff

The portable database endpoints are the database backup and migration boundary. Export resolves the source database only from the requested manifest serviceId; import resolves the target database and tenant user only from the pre-provisioned targetServiceId. A caller cannot select a target database name or username.

/resources/database/digest accepts only { "serviceId": "..." } in a body of at most 16 KiB and resolves the database through the same manifest ownership boundary. It returns schemaVersion: 1, the resolved service/resource/database source descriptor, and SmartDB's smartdb.database.content-digest.v1 result. The digest covers collection names, exact BSON document bytes, and persisted index specifications while normalizing enumeration order only. BSON field order and compound-index key order remain significant. Scans are capped at 96 MiB of BSON, 10,000 collections, 1,000,000 documents, and 100,000 indexes. Compare digest.sha256 and the counters when proving equal content across source and restored databases; do not compare the complete digest objects because digest.databaseName is intentionally service-specific.

The version 1 payload contains canonical UTF-8 JSON bytes for smartdb.database.export.v1, encoded as base64 with an exact byte count and SHA-256. Corestore rejects non-canonical base64, invalid UTF-8, a non-canonical JSON encoding, descriptor mismatches, payloads above 16 MiB, and complete portable request bodies above 24 MiB. SmartDB export is additionally capped at 10,000 collections, 1,000,000 documents, and 100,000 indexes.

Corestore-native database snapshots created by /resources/snapshot and consumed by ordinary or isolated resource restore use a separate 96 MiB payload ceiling. This matches the explicit offline MongoDB-wire migration envelope without weakening the 16 MiB portable API boundary. The archive reader admits only the single trailing newline written by Corestore in addition to that payload.

Import requires a stable restoreId and positive orchestrationFence. Portable-import fences are monotonic within the portable API's own ordering domain; internal snapshot and isolated-restore attempts use a separate ordering domain and cannot make the next valid portable fence stale. Corestore durably binds the request to one SmartDB fence through SmartData exact persistence before mutating the database. When no SmartData record exists yet, Corestore first inspects SmartDB's durable released high-water mark and continues at the next token; an active publication, identity mismatch, corrupt state, or exhausted token fails before any coordination record or provider mutation is created. An exact retry after response loss or restart returns the same held receipt; after commit it returns the released receipt. Reusing a completed restoreId, submitting a stale portable orchestration fence, or conflicting with an active mutation returns 409. The imported database remains unavailable until publication is committed.

The orchestrator must follow this order:

1. Call /resources/database/import and receive the held receipt.
2. Persist the complete receipt and migration checkpoint durably.
3. Call /resources/database/import/commit with that exact receipt.

Digest, import, export, commit, and their error responses use Cache-Control: no-store. Corestore admits only one memory-bounded portable database operation at a time, rejects concurrent mutations for the same database without queueing them, aborts response delivery on shutdown or disconnect, applies a delivery deadline, and gives lifecycle-critical SmartDB management and health calls a five-minute fail-stop deadline. It retains bounded monotonic restore history for each target and ordering domain. Provision, restore, isolated restore, and deprovision share the same per-database resource-mutation namespace; there is no unfenced database mutation path in normal Corestore operation.

Selected database backup closures

The database backup endpoints are the operator-scoped backup transport for database payloads larger than the 16 MiB portable handoff envelope. Export accepts a JSON object of at most 16 KiB with exactly schemaVersion: 1, serviceId, and backupId. Corestore creates one database snapshot with controlled ownership tags, exports the exact snapshot closure through ContainerArchive, and returns the opaque closure with an authenticated, non-cacheable receipt header. MongoDB wire protocol remains the workload interface before and after backup; the closure transports SmartDB's canonical database snapshot representation.

The underlying SmartDB snapshot payload is capped at the 96 MiB Corestore-native database envelope. Closure transfer is capped at 256 MiB, 4,096 immutable archive objects, 128 MiB of verified selected plaintext, a 16 KiB canonical receipt header, and five minutes without transfer progress. Restore requires one exact Content-Length, identity transfer encoding, no content encoding, and byte length equal to the receipt. It imports only into a new private disposable staging repository, validates the exact one-snapshot ownership and item contract, restores into a pre-provisioned target service database through the normal durable SmartDB fence, and removes staging before returning success.

The restore identity binds the backup, source and target resource identities, snapshot ID, and closure digest. An exact retry after response loss or restart resumes the same held publication, returns the same released mutation, or proves the matching completed history entry. It never starts a second unrelated database replacement.

Selected closure is a semantic backup boundary, not a byte-level tenant-confidentiality boundary. ContainerArchive excludes unrelated snapshot manifests and unselected global-index entries, but immutable reachable packs can contain physical bytes or sidecar descriptions shared with other snapshots. Keep these artifacts inside the trusted operator backup boundary. Onebox continues to back up object storage through the streaming S3 API rather than this database-only closure endpoint.

The repository-wide /archive/manifest and /archive/object/* endpoints are legacy node-replication surfaces used by the current Coreflow backup path. They are not safe service-selected backup APIs and must not be used by new consumers; they remain only until Coreflow moves to selected closures.

Named storage bindings

The v2 API consumes the shared @serve.zone/interfaces App Store request/class shapes and returns platform.TResolvedStorageBinding. The request contains portable policy only. Provider names, host paths, network shares, authentication mechanisms, mount options, endpoint overrides, and bucket names are rejected as unknown physical fields.

Example object-storage reconciliation:

{
  "schemaVersion": 2,
  "bindingId": "binding:backup-archive",
  "serviceId": "Service:example",
  "generation": 1,
  "policy": {
    "classId": "corestore.object-storage.standard.v1",
    "revision": "1"
  },
  "storageClass": {
    "kind": "objectStorage",
    "purpose": "backup",
    "required": {
      "durability": "persistent"
    }
  },
  "request": {
    "id": "backup-archive",
    "kind": "objectStorage",
    "storageClass": "archiveStorage",
    "reclaimPolicy": "retain",
    "accessMode": "readWrite",
    "delivery": {
      "type": "launcher-environment",
      "keys": {
        "endpoint": "ARCHIVE_S3_ENDPOINT",
        "bucket": "ARCHIVE_S3_BUCKET",
        "region": "ARCHIVE_S3_REGION",
        "accessKeyId": "ARCHIVE_S3_ACCESS_KEY_ID",
        "secretAccessKey": "ARCHIVE_S3_SECRET_ACCESS_KEY"
      }
    }
  },
  "credentialManagementScope": "platform:object-storage-binding"
}

Corestore computes the canonical request digest; callers cannot supply one. Stable (serviceId, request.id) and binding identities are unique. The same generation and intent is idempotent, stale generations fail, and changed intent requires an explicit migration. Binding records are strictly revalidated on every SmartData read and write, updated through revision compare-and-swap, and fenced by operation leases. The value-free credentialManagementScope describes platform ownership without storing or coupling the binding to a secret record.

Release is a durable replay-safe lifecycle: the release intent is recorded before provider deletion, provider deletion is idempotently retried after a crash, and terminal retained or released tombstones prevent allocation-id reuse. Reconcile cannot resume after release starts. Provider and persistence details are reduced to fixed failure messages; binding responses and persisted failures never expose provider credential material or raw provider errors.

Object-storage placement is the selected policy class revision: portable workload requirements never contain host paths, NFS exports, SMB shares, or provider endpoint overrides. Pool catalog records, binding placement, migration ownership, and migration state are SmartData-authoritative and survive process restarts.

Changing a live object's class is an explicit migration, never an in-place reconcile. Corestore creates a hidden destination, copies every object with exact create-only publication and preserved supported metadata, asks the orchestrator to quiesce the consumer, establishes a source seal, verifies the destination manifest, publishes the durable binding cutover, waits for consumer activation evidence, and only then performs fenced source cleanup. Abort is allowed only before the commit point; after cutover, recovery rolls forward.

The configured classes deliberately advertise only guarantees the named lifecycle enforces:

• Filesystem: persistent, single-node, ReadWriteOnce, standard performance.
• Default object storage: persistent, single-node, read-write, standard performance, with optional compliance retention.
• Additional object-storage pools may advertise exactly one of standard, high-IOPS, or capacity performance when the operator maps that class to a matching physical backend.
• No hard quotas, snapshot/backup guarantee, versioning, read-only object policy, multi-node topology, or transport-encryption guarantee yet.
• Every hard capacity quantity is rejected until Corestore can reserve and report an enforced byte limit. Session-token delivery is rejected until Corestore can issue actual session credentials.

Reconcile, get, and list responses never contain provider credential values. The separate credentials endpoint requires the current service id and generation, returns semantic credential material, and is non-cacheable. The fulfillment adapter maps that material to the App Store request's launcher-environment or file delivery contract.

Each isolated-restore request body carries a restoreGrant compact JWT in addition to its versioned request fields. Grants use RS256, identify a configured key by kid, authorize exactly one operation, expire within five minutes by default, bind the target cluster and node, and bind the canonical resource-mapping and archive-manifest hashes. Corestore rejects a grant when any bound request value differs.

Snapshot a volume:

curl -X POST http://corestore:3000/volumes/snapshot \
  -H 'content-type: application/json' \
  -H 'authorization: Bearer <CORESTORE_API_TOKEN>' \
  -d '{"name":"sz-api-data-abc123","snapshotName":"before-deploy"}'

Restore a volume snapshot:

curl -X POST http://corestore:3000/volumes/restore \
  -H 'content-type: application/json' \
  -H 'authorization: Bearer <CORESTORE_API_TOKEN>' \
  -d '{"name":"sz-api-data-abc123","snapshotId":"<snapshot-id>","clear":true}'

Docker Volume Driver

Corestore implements these Docker VolumeDriver endpoints over its Unix socket:

• /Plugin.Activate
• /VolumeDriver.Capabilities
• /VolumeDriver.Create
• /VolumeDriver.Remove
• /VolumeDriver.Mount
• /VolumeDriver.Unmount
• /VolumeDriver.Path
• /VolumeDriver.Get
• /VolumeDriver.List

The Corestore service must bind mount /run/docker/plugins from the host so Docker can discover /run/docker/plugins/corestore.sock.

Volume mountpoints are real host directories under:

<CORESTORE_DATA_DIR>/volumes/<safe-volume-name>-<hash>/data

Docker bind-mounts those paths into workload containers. Corestore tracks mount ids, service metadata, backup flags, and snapshot history in corestore-manifest.json.

Coreflow Integration

The intended platform behavior is:

• Coreflow deploys Corestore as a global service so each workload node has a local storage provider.
• New portable filesystem and object-storage requests are matched against /control/v2/storage/capabilities and reconciled through stable v2 binding ids.
• Coreflow obtains object-storage credential values only from the authenticated non-cacheable credentials endpoint, then applies the declared launcher-environment or file delivery contract.
• The resolved filesystem resourceRef is handed to the runtime volume attachment; physical attachment details do not enter App Store manifests.
• Workload platform bindings for database and objectstorage call /resources/provision.
• First-class workload volumes use Docker DriverConfig.Name = 'corestore' by default.
• Backup orchestration snapshots volumes through /volumes/snapshot and service resources through /resources/snapshot; portable database transfer uses /resources/database/export.
• Ordinary local restore orchestration uses /volumes/restore, /resources/restore, and archive object read/write endpoints. Database restore is internally routed through the same durable import/commit fence as portable handoff.
• Authorized scratch-environment recovery uses the signed /isolated-restore/* prepare, object-write, execute, status, and cleanup sequence. Each phase receives a new operation-scoped grant from the control plane.

Docker Image

pnpm run build:docker

The image exposes 3000, 9000, and 27017 and stores runtime data under /data/corestore unless CORESTORE_DATA_DIR overrides it.

Development

Common commands:

pnpm install
pnpm build
pnpm test
pnpm run watch

Important files:

Path	Purpose
ts/index.ts	CLI startup wrapper exporting CoreStore, runCli, and stop.
ts/corestore.classes.corestore.ts	Main runtime, control API, VolumeDriver API, provisioning, snapshots, and archive replication.
ts/corestore.interfaces.ts	Request, response, manifest, resource, and snapshot types.
ts/corestore.storage.ts	Strict portable v2 contract normalization, capability negotiation, digests, and collision checks.
ts/corestore.classes.storagebindingstore.ts	SmartData-authoritative named-binding records and unique identities.
ts/corestore.objectstoragepools.ts	Strict physical pool configuration, portable class mapping, and immutable pool identities.
ts/corestore.plugins.ts	Centralized dependency imports.
ts/corestore.classes.controlauth.ts	Strict bearer-token and token-file validation.
ts/corestore.classes.restoregrant.ts	Signed isolated-restore grant verification and node binding.
ts/corestore.classes.isolatedrestorecoordinator.ts	Durable leases, fencing, receipts, reconciliation, and crash recovery.
ts/corestore.classes.safetar.ts	Bounded fail-closed archive extraction.
ts_migration/legacy-mongodb-to-smartdb.ts	Explicit offline MongoDB-wire to SmartDB migration with compatibility preflight, publication fencing, and exact verification.
migration.js	Operator-only migration entrypoint included in the container image and package.

License and Legal Information

This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the license file.

Please note: The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.

Trademarks

This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH or third parties, and are not included within the scope of the MIT license granted herein.

Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines or the guidelines of the respective third-party owners, and any usage must be approved in writing. Third-party trademarks used herein are the property of their respective owners and used only in a descriptive manner, e.g. for an implementation of an API or similar.

Company Information

Task Venture Capital GmbH Registered at District Court Bremen HRB 35230 HB, Germany

For any legal inquiries or further information, please contact us via email at hello@task.vc.

By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.