ADAMANT IPFS Node v0.1.0 released from master: bounded storage, deterministic replication, and Tor-ready CORS

[metalisk]

The first tagged release of ADAMANT IPFS Node is now cut from master: v0.1.0, with the container at ghcr.io/adamant-im/ipfs-node:0.1.0. This supersedes the earlier dev-based tag and the progress thread #74.

The node is a universal, self-hostable open-source product: an IPFS storage node for application file delivery, with bounded disk usage, deterministic replication, repair, health checkpoints, and a REST API. It is a standalone Node.js and Helia application, not a Kubo wrapper and not a Kubo-compatible API. ADAMANT Messenger is one adopter and the reference deployment, not the product's purpose — any application can self-host it.

What this cut contains

Service runtime. Express over twelve documented paths (health, public /api/node/info, administrative /api/node/details, multipart upload, download by CID, per-file status, confirm/unpin, storage metrics and policy, administrative GC and repair triggers), with access classes enforced centrally in src/security/accessPolicy.ts. The admin key fails closed; CORS is an explicit allowlist and never authentication; per-endpoint rate limits, validated trustProxy, upload/download admission control, and controlled public errors round it out.

Storage lifecycle. Datastore-backed file registry with a durable state machine, disk reserve, aggregate request limits, intake budget, temporary uploads with TTL, watermark-driven GC with dry-run plan, per-CID locks, sweep batching, and pin management. Placement is deterministic rendezvous hashing over the configured peer set, with copy counts shrinking by file age. Replication runs over versioned /adamant/replication/1.0.0 (prepare/commit/rollback staging); a resumable repair cycle carries its own claim, cursor, and evidence. Each upload session tracks the blocks it created, so a rejected or aborted request removes exactly those.

Health. Network-aware checkpoints with persisted monotonic height and an explicit membership epoch; /adamant/health/1.0.0 accepts attestations only from configured peers. GET /api/node/health always answers 200 with state of starting, ready, stale, or degraded.

Mesh reliability (new since the dev tag). #40 adds periodic libp2p ping liveness checks with session reset on failure and reactive recovery after stale replication stream errors or retrieval timeouts, fixing cross-node HTTP 408s on zombie sessions. #42 adds optional health.repairBacklogGraceCycles with consecutiveUnsuccessfulCycles on health endpoints, raises ping stream limits with per-peer coalescing, recovers sessions without a ping veto, settles hangUp up to 1,000 ms before redial with one placement retry on the fresh connection, and attributes replication-wire timeouts versus unexpected endings.

CORS and error codes (new since the dev tag). #45 adds an opt-in exact app://. desktop origin and stable machine-readable code values next to error text (rate_limited, upload_concurrency, download_concurrency, download_client_concurrency, request_too_large, insufficient_storage, replication_quorum, file_timeout), plus unified trustProxy guidance. #47 adds http(s)://*.onion wildcards limited to v3 hidden-service shapes and an opt-in literal null origin for Tor Browser cross-.onion requests. #48 answers Access-Control-Allow-Origin: * for the opted-in null origin instead of reflecting null, drops the Referer rewrite, and registers Vary: Origin before the CORS middleware.

Container. Multi-stage Dockerfile on node:24.13.0-bookworm-slim, unprivileged node user, HOME=/data so one volume holds blockstore, datastore, peer identity, pins, registry, repair cursor, and health checkpoint. The image ships no configuration; mount one at /app/config.json5. Published for linux/amd64 and linux/arm64 with SBOM and provenance attestation; docker/config.example.json5 joins no network.

Boundaries

No DHT, no IPNS, no public gateway, no Kubo API. Stored content is not announced to the public IPFS network, and public-network content cannot be fetched through this node. A controlled peer topology avoids the public DHT and public gateways and reduces public exposure of content-routing metadata, but it does not by itself make a deployment private, anonymous, trustless, or censorship-proof. Upload and download are unauthenticated by design; the only credential is one administrative key. Open work: uploader-signed deletion (#27), peer discovery (#28), traffic accounting (#29), absolute data directory (#30), public-network interop (#31).

Run it

docker volume create ipfs-node-data

docker run -d \
  --name ipfs-node \
  --restart unless-stopped \
  --stop-timeout 20 \
  -v ipfs-node-data:/data \
  -v "$PWD/config.json5:/app/config.json5:ro" \
  -p 127.0.0.1:4000:4000 \
  -p 4001:4001 \
  ghcr.io/adamant-im/ipfs-node:0.1.0

Start at the use cases and comparison pages before designing around the node. Operators upgrading from a pre-dev service should read Migrating an older configuration: peeringSchedule replaces autoPeeringPeriod, cors.allowedOrigins replaces the old CORS keys, identity fields moved from /api/node/info to key-gated /api/node/details, and the provider-lookup route no longer exists.

Verification

Release track: issue #37, merge PR #38 (dev into master). CI, Security Audit, Docs, and Container pass on the merge; the Container job builds and smoke-tests the image on both architectures. The Publish container workflow runs from the master-cut tag, verifies the tag is an ancestor of master and matches package.json 0.1.0, then rebuilds 0.1.0/latest with ADAMANT OCI labels, SBOM, and provenance, and re-pulls each architecture for a second smoke test.

Links

• Release: https://github.com/Adamant-im/ipfs-node/releases/tag/v0.1.0
• Container: https://github.com/Adamant-im/ipfs-node/pkgs/container/ipfs-node
• Documentation: https://ipfs-node.docs.adamant.im
• API specification: https://ipfs-node.docs.adamant.im/openapi.yaml
• Source: https://github.com/Adamant-im/ipfs-node