opencloudmesh-go

module

v1.3.1 Latest Latest Go to latest Published: Sep 9, 2026 License: AGPL-3.0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/MahdiBaghbani/opencloudmesh-go

Links

Open Source Insights

README ¶

OpenCloudMesh Go

A runnable Open Cloud Mesh peer in Go, focused on a strict, WebDAV-centered subset of the protocol.

OpenCloudMesh Go is a Go server for Open Cloud Mesh (OCM). It focuses on a pinned, practical slice of the protocol: discovery, user shares, invite flows, the strict authorization-code flow, HTTP signatures and JWKS, and Bearer WebDAV access on that path.

This repository is not the OCM specification itself, and it does not claim full OCM-API coverage or broad compatibility with arbitrary peers. What it does try to offer is narrower and more useful: a documented strict contract, a pinned spec snapshot, and a real server you can run, test, and extend.

Status: active development. The strict contract is the part that is supported and tested on every change; expect the edges outside it to keep moving.

Why OpenCloudMesh Go

When a discovery stub is not enough, you usually want a real peer you can talk to, a clear idea of what "strict" means, and a codebase that does not hide the interesting parts behind magic. That is what this repo is trying to be.

It gives you a runnable OCM peer in Go, keeps the scope explicit instead of pretending to implement everything, and pins behavior to a specific OCM-API snapshot. It also tries to make the security story legible: signatures, transport, and trust are deliberate knobs rather than silent fallbacks.

Right now that means discovery, user-share flows on the WebDAV-centered path, invite handling, accept flows, optional WAYF support, the strict authorization-code flow on the documented OCM route surface, and a bundled UI and API for practical local and multi-instance workflows.

For the exact route surface, start with docs/protocol-endpoints.md and docs/discovery.md.

Who it is for

You will probably get the most out of this if you are building or testing OCM peers and want something concrete to talk to, if you are studying how a signature-aware, WebDAV-centered OCM flow actually fits together, or if you need a Go server whose scope and guarantees are written down rather than implied. If you are looking for a full, drop-in OCM implementation that federates with every peer out there, this is not that yet, and it is honest about it.

What passing tests mean

The repo ships unit tests, architecture guard tests, integration tests, and optional Playwright E2E flows. They matter, but they do not all prove the same thing, and this README should not pretend otherwise.

The narrow contract this repo stands behind lives in docs/verification-boundary.md. If you want to know what a green strict run actually proves, what remains operator-managed, and what this project does not claim about arbitrary peers, read that file first.

Quickstart

From the repo root:

# Build the server binary
make build

# Run unit and integration tests
make test

# Start the server in strict mode (default)
./bin/opencloudmesh-go

# Check discovery
curl http://localhost:9200/.well-known/ocm

Useful local variants:

# Dev preset
./bin/opencloudmesh-go -mode dev

# Validator preset
./bin/opencloudmesh-go -mode validator

# Strict preset with a TOML file
./bin/opencloudmesh-go -config docker/configs/config-tls.toml

# Override from the CLI
./bin/opencloudmesh-go -mode strict -public-origin https://localhost:9200

See it work

The quickest way to watch two peers talk is the bundled two-instance runner. It builds the binary and starts a sender and a receiver side by side:

./scripts/dev/two-instance.sh

That gives you a sender on http://localhost:9200 and a receiver on http://localhost:9201, both ready for a local share flow. Hit Ctrl+C to stop both. From there you can open discovery on each, or drive an invite and accept between them.

Presets and configuration

The server resolves config in this order: preset bundle, TOML file, CLI flags.

The shipped preset bundles are strict, dev, and validator. They are good starting points; effective behavior also depends on signature, transport, and trust settings.

If you are getting oriented, start here:

Useful sample configs:

configs/validator.toml for the federation-validator preset (statistics, trusted proxies). On mode=validator, including passive-only, GET /validator/api/scan is public, anonymous, rate-limited 10/60, and SSRF-guarded. See docs/configuration.md.
docker/configs/config.toml for a minimal container-oriented dev setup
docker/configs/config-tls.toml for a strict setup with static TLS
tests/ca_pool/configs/valid.toml and invalid.toml for outbound root CA validation

Documentation

Core docs

Governance and security

Protocol and runtime behavior

Test guides

cmd/opencloudmesh-go/     Binary entrypoint
internal/                 Production and test-support code
  architecture/           Architecture guard tests
  components/             Domain logic (ocm, api, identity, ...)
  frameworks/             Service registry and startup
  interceptors/           HTTP middleware (ratelimit, ...)
  platform/               Config, HTTP, cache, store, repos
  services/               HTTP route handlers
  testsupport/            Test-only helpers (not for production)
  wiring/                 Composition root
tests/                    Integration, E2E, and CA pool tests
docs/                     Developer and protocol documentation
docker/                   Container image and sample configs

See docs/repo-layout.md for the full map.

Build and test

make build
make test-go
make test-integration
make test
make test-e2e-install
make test-e2e
make fmt
make vet
make tidy

make test runs unit and integration tests. E2E stays separate because it needs Bun, Playwright, and a built binary.

Docker

Build the local image:

./scripts/build-docker.sh
# or: docker build -t opencloudmesh-go:local -f docker/Dockerfile .

Run in HTTP mode:

docker run -d -p 8080:8080 -e HOST=ocm-go1 opencloudmesh-go:local
curl http://localhost:8080/.well-known/ocm

Run in TLS mode with the pre-installed certs:

docker run -d -p 443:443 -e HOST=ocm-go1 -e TLS_ENABLED=true opencloudmesh-go:local
curl -k https://localhost/.well-known/ocm

Set at least one of HOST or PUBLIC_ORIGIN. The full environment-variable reference, including TLS material and how the entrypoint derives the public origin, lives in docs/docker.md.

DeepWiki

If you want a browsable, AI-generated overview of the repository, see DeepWiki. The files under docs/ are still the source of truth.

Ecosystem

OpenCloudMesh Go sits in the middle of the wider OCM stack. The protocol lives in cs3org/OCM-API. This repo provides a runnable Go server for a focused OCM slice, and downstream container and interoperability setups use it alongside the wider OCM image and test tooling.

Protocol behavior is pinned to the OCM-API snapshot at 6a0586183cbef10ecae9dedc42561806447eb2f5, with the vendored pin recorded in internal/components/ocm/spec/vendor/pin.json.

Acknowledgements

OpenCloudMesh Go exists because someone chose to fund open source infrastructure. A big thank you to the Sovereign Tech Agency for backing this work, which Mahdi Baghbani develops as part of Open Cloud Mesh.

You can read the full story in FUNDING.md.

Contributing

Contributions are welcome. See CONTRIBUTING.md for the development workflow, validation commands, and pull request expectations.

Questions and issues

Bug reports, questions, and ideas are welcome on the issue tracker. If something in the docs is unclear or wrong, that is worth an issue too.

License

Licensed under the GNU Affero General Public License v3.0 or later (AGPL-3.0-or-later). See LICENSE.

Directories ¶

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

Path	Synopsis
cmd
opencloudmesh-go command Package main runs the OCM reference implementation server.	Package main runs the OCM reference implementation server.
internal
components/api Package api provides shared HTTP API handlers (auth, health) and standardized error responses.	Package api provides shared HTTP API handlers (auth, health) and standardized error responses.
components/api/inbox/invites Package invites provides session-gated API handlers for inbox invites (list, import, accept, decline).	Package invites provides session-gated API handlers for inbox invites (list, import, accept, decline).
components/api/inbox/shares Package shares provides session-gated API handlers for inbox shares (list, detail, accept, decline, verify-access).	Package shares provides session-gated API handlers for inbox shares (list, detail, accept, decline, verify-access).
components/api/outgoing/invites Package invites provides the session-gated handler for POST /api/invites/outgoing (create invite tokens).	Package invites provides the session-gated handler for POST /api/invites/outgoing (create invite tokens).
components/api/outgoing/shares Package shares provides the session-gated handler for POST /api/shares/outgoing (create shares to remote receivers).	Package shares provides the session-gated handler for POST /api/shares/outgoing (create shares to remote receivers).
components/federationvalidator/active/forwardshare Package forwardshare implements the validator's active forward-share dispatch leg: a policy guard on the generic outgoing-share handler that refuses every non-designated share while a run is active, plus the outbox-backed designated dispatch with a single-winner send permit, idempotent replay, and capability presence healing.	Package forwardshare implements the validator's active forward-share dispatch leg: a policy guard on the generic outgoing-share handler that refuses every non-designated share while a run is active, plus the outbox-backed designated dispatch with a single-winner send permit, idempotent replay, and capability presence healing.
components/federationvalidator/active/identitybind Package identitybind canonicalizes OCM invite identities for the federation-validator active path.	Package identitybind canonicalizes OCM invite identities for the federation-validator active path.
components/federationvalidator/active/reverseinvite Package reverseinvite implements the validator's active reverse-invite leg: atomic outgoing invite minting, outgoing-acceptance observation, reverse solicit, paste import, and acceptance orchestration against the live OCM invite domain operations.	Package reverseinvite implements the validator's active reverse-invite leg: atomic outgoing invite minting, outgoing-acceptance observation, reverse solicit, paste import, and acceptance orchestration against the live OCM invite domain operations.
components/federationvalidator/active/reverseshare Package reverseshare implements the validator's active reverse-share leg: the event-driven wait opened after the capability exercise, the inbound share observer that passes the run on a timely or late reverse share, and the durable terminal-stats retry behind both.	Package reverseshare implements the validator's active reverse-share leg: the event-driven wait opened after the capability exercise, the inbound share observer that passes the run on a timely or late reverse share, and the durable terminal-stats retry behind both.
components/federationvalidator/active/runner Package runner drives the validator active-session kick and heal loop.	Package runner drives the validator active-session kick and heal loop.
components/federationvalidator/catalog Package catalog is the validator route and capability SSOT.	Package catalog is the validator route and capability SSOT.
components/federationvalidator/core Package core holds federation validator shared state wired at startup.	Package core holds federation validator shared state wired at startup.
components/federationvalidator/httpsigprobe Package httpsigprobe runs a signed two-request differential against a probe-only dummy URL.	Package httpsigprobe runs a signed two-request differential against a probe-only dummy URL.
components/federationvalidator/jwksprobe Package jwksprobe fetches and grades a peer JWKS document without store I/O.	Package jwksprobe fetches and grades a peer JWKS document without store I/O.
components/federationvalidator/passive
components/federationvalidator/platformdetect
components/federationvalidator/tlsprobe
components/identity Package identity provides user management, authentication, and session handling.	Package identity provides user management, authentication, and session handling.
components/identity/sessiongate Package sessiongate provides session authentication middleware for HTTP servers.	Package sessiongate provides session authentication middleware for HTTP servers.
components/ocm/access Package access provides remote file access for incoming OCM shares.	Package access provides remote file access for incoming OCM shares.
components/ocm/address Package address provides OCM address parsing and formatting.	Package address provides OCM address parsing and formatting.
components/ocm/directoryservice Package directoryservice fetches and verifies OCM directory service listings.	Package directoryservice fetches and verifies OCM directory service listings.
components/ocm/discovery
components/ocm/discovery/resolve Package resolve derives OCM discovery provider configuration from service-local TOML plus narrow ResolveInputs supplied by wiring.	Package resolve derives OCM discovery provider configuration from service-local TOML plus narrow ResolveInputs supplied by wiring.
components/ocm/inbound/signature Package signature verifies inbound OCM HTTP request signatures.	Package signature verifies inbound OCM HTTP request signatures.
components/ocm/invites Package invites provides shared types for OCM invitations.	Package invites provides shared types for OCM invitations.
components/ocm/invites/incoming Package incoming provides incoming invite models, repository, and the invite-accepted domain port used when we accept a received invite.	Package incoming provides incoming invite models, repository, and the invite-accepted domain port used when we accept a received invite.
components/ocm/invites/outgoing Package outgoing provides outgoing invite models and repository.	Package outgoing provides outgoing invite models and repository.
components/ocm/invites/outgoing/accepted Package accepted handles POST /ocm/invite-accepted, which remote recipients call to accept one of OUR outgoing invites.	Package accepted handles POST /ocm/invite-accepted, which remote recipients call to accept one of OUR outgoing invites.
components/ocm/notifications Package notifications provides shared OCM notification types and errors.	Package notifications provides shared OCM notification types and errors.
components/ocm/notifications/incoming
components/ocm/notifications/outgoing Package outgoing posts OCM share lifecycle notifications to remote peers.	Package outgoing posts OCM share lifecycle notifications to remote peers.
components/ocm/outbound Package outbound centralizes the shared OCM outbound POST flow: resolve the peer origin, discover the peer endpoint, sign when configured, and send the request.	Package outbound centralizes the shared OCM outbound POST flow: resolve the peer origin, discover the peer endpoint, sign when configured, and send the request.
components/ocm/peer Package peer provides peer resolvers for OCM signature middleware.	Package peer provides peer resolvers for OCM signature middleware.
components/ocm/peerorigin Package peerorigin resolves peer origin (scheme and base URL) and validates absolute-URI peer authorities for OCM outbound and inbound peer-boundary callers.	Package peerorigin resolves peer origin (scheme and base URL) and validates absolute-URI peer authorities for OCM outbound and inbound peer-boundary callers.
components/ocm/peertrust Package peertrust manages trust groups and peer allow/deny policy.	Package peertrust manages trust groups and peer allow/deny policy.
components/ocm/policy Package policy resolves OCM code-flow facts for peers.	Package policy resolves OCM code-flow facts for peers.