Skip to main content

Registry Service

The registry is a separate backend service at registry.getarcan.dev. It is NOT part of the Arcan core binary.

Responsibilities​

  • Host plugin packages (.arcanpkg files -- platform-independent when WASM, multi-platform for compiled)
  • Compile plugin source code into packages (build service -- authors push source, we build and sign)
  • Serve plugin metadata (version, capabilities, checksums, signatures)
  • Validate enterprise activation keys
  • Track download counts and version adoption (for us, not user telemetry)

API Surface​

Public (no auth)​

GET  /v1/plugins                                              → list all plugins
GET  /v1/plugins/{name}                                       → plugin metadata + all versions
GET  /v1/plugins/{name}/{version}/meta                        → checksums, signatures, capabilities
GET  /v1/plugins/{name}/{version}/download/{os}/{arch}        → binary download (official tier)

Enterprise (activation token required)​

POST /v1/activate                                             → validate key, bind to fingerprint
POST /v1/heartbeat                                            → periodic validation (every 7 days)
GET  /v1/plugins/{name}/{version}/download/{os}/{arch}        → binary download (enterprise tier)
     Header: Authorization: Bearer <activation_token>

Internal (CI/CD, admin API key)​

POST /v1/plugins/{name}/{version}/publish                     → upload new version
POST /v1/plugins/{name}/{version}/yank                        → mark version as yanked

Plugin Metadata Format​

{
    "name": "postgres",
    "version": "0.1.0",
    "tier": "official",
    "protocol_version": 1,
    "min_core_version": "0.1.0",
    "capabilities": ["dynamic_credentials", "root_rotation"],
    "description": "Dynamic credentials for PostgreSQL databases",
    "platforms": ["linux/amd64", "linux/arm64", "darwin/amd64", "darwin/arm64"],
    "checksums": {
        "linux/amd64":  "sha256:abc123...",
        "linux/arm64":  "sha256:def456...",
        "darwin/amd64": "sha256:789abc...",
        "darwin/arm64": "sha256:012def..."
    },
    "signature": "ed25519:<base64-signature-of-checksums>",
    "size_bytes": {
        "linux/amd64": 12345678,
        "darwin/arm64": 11234567
    },
    "published_at": "2026-04-01T00:00:00Z",
    "yanked": false,
    "yank_reason": ""
}

Backend Stack​

  • Go service (same standards as Arcan core)
  • PostgreSQL (plugin metadata, activation records, download stats)
  • S3 (binary storage -- versioned objects, immutable after upload)
  • CloudFront (binary delivery -- edge cached)
  • Domain: registry.getarcan.dev

Security Rules​

  • All packages signed with Ed25519 before publishing (build service signs, never humans).
  • Signing private key stored in AWS KMS, never on disk, never in code.
  • Official signing public key embedded in Arcan core binary (compiled in).
  • Enterprise signing public key distributed in activation response.
  • Yanked versions return 410 Gone with reason (security advisory link).
  • Rate limiting: 100 req/min per IP on download, 10 req/min on metadata.
  • No user telemetry -- download counts are aggregate, not per-user.
  • Plugin source code can be public (open-source) or private (enterprise/community).