Private binary download endpoint for paying customers

@@ -13,10 +13,10 @@ status: active
audience: vendor-public
bcsc_class: no-disclosure-implication
language_protocol: PROSE-TOPIC
last_edited: 2026-07-11
last_edited: 2026-08-22
editor: pointsav-engineering
paired_with: private-git-paid-customer-endpoint.es.md
short_description: "The binary release server behind software.pointsav.com verifies Ed25519 license tokens and streams compiled binaries — stateless, holding no payment records or keys."
short_description: "The binary release server behind software.pointsav.com verifies Ed25519 license tokens and streams compiled binaries — stateless, holding no payment records or keys, with some products served openly and no license check at all."
cites: []
---

@@ -24,99 +24,73 @@ The binary release server is the component of `software.pointsav.com` that deliv
compiled binaries to paying customers. It is a thin, stateless gate: it holds no payment
records, no customer data, and no signing keys. Its sole responsibility is to verify that
a presented license token is genuine and authorises the requested product, then stream
the binary file. A customer who has completed a purchase and holds a valid token can
download the corresponding binary without any further interaction with the payment
infrastructure.
the binary file.

## Route structure

The release server organises its endpoints into four categories.

**Product and version discovery.** An unauthenticated product index lists all products
whose releases are available on the server, and a version index lists all available
versions for a given product. These endpoints require no license token and are designed
for consumption by tooling such as package managers, installer scripts, and CI pipelines.
**Product and version discovery.** An unauthenticated products index lists every product
with releases on the server; a per-product index lists that product's available versions.
Both are designed for tooling — package managers, installer scripts, CI pipelines.

**Versioned binary download.** The primary gated endpoint serves a binary for a specific
product, version, and platform. Requests to this endpoint require a valid license token.
A detached Ed25519 signature file for each binary is available at a corresponding path
and is always unauthenticated — detached signatures are public by design, allowing any
party to verify the authenticity of a binary without holding a license.
product, version, and platform, and requires a valid license token — with one exception:
a product whose manifest sets `requires_license: false` is served to anyone, no token
required. A detached Ed25519 signature file for each binary is available at a
corresponding path and is always unauthenticated — detached signatures are public by
design, letting any party verify a binary's authenticity without holding a license.

**Latest-version redirect.** A convenience endpoint resolves the highest available version
for a given product and platform and issues a redirect to the versioned download path. The
license token is forwarded through the redirect. The redirect only targets platform and
version combinations for which a release actually exists; it will not redirect to a version
that lacks a binary for the requested platform.
for a given product and platform and issues a redirect to the versioned download path,
forwarding the license token through. It only redirects to a platform for which a release
actually exists.

**Release manifest.** A per-version metadata endpoint serves a structured manifest
describing the contents of a release. No authentication is required. This endpoint is
useful for tooling that needs to inspect what a release contains before initiating a
download.
**Release manifest and install script.** A per-version manifest endpoint and a per-product
`install.sh` endpoint are both unauthenticated, letting tooling inspect a release or fetch
an installer without a license token.

**Token introspection.** An authenticated endpoint returns metadata about the presented
token itself — its associated product and expiry — without initiating a download. A
separate, unauthenticated health-probe endpoint supports uptime monitoring.
**Token introspection.** An authenticated endpoint checks a presented token against a
product and returns its validity, product ID, version floor, channel expiry, and
entitlements — without initiating a download. A separate endpoint serves the server's own
public verification key in hex, so a client can verify a detached signature independently.
A health-probe endpoint supports uptime monitoring.

## Authentication

The release server accepts a license token in two forms.

**HTTP Authorization header.** The token is passed as a Bearer credential in the
`Authorization` header. This is the standard form for programmatic clients, automated
installers, and command-line tools that can set arbitrary request headers.

**Query parameter.** The token is passed as a `token` parameter appended to the URL.
This form exists specifically to enable browser-initiated one-click download links: a
storefront can generate a URL that includes the token, allowing a customer to download
a binary directly from their browser without configuring any HTTP headers. Both forms are
equally secure — neither exposes the token to additional parties beyond the client and
the server.
The release server accepts a license token as an `Authorization: Bearer` header or as a
`token` query parameter. The query-parameter form exists specifically for browser-initiated
one-click downloads: a storefront can generate a URL carrying the token so a customer can
download directly from their browser with no header configuration. Both forms are equally
secure — neither exposes the token to any party beyond the client and the server.

## Verification logic

The server decodes the base64url token string, splits off the first 64 bytes as an Ed25519
signature, and verifies the signature over the remaining bytes using the server's stored
public verification key. It then parses the payload and checks two things: that the
product field in the payload matches the product being requested, and that the expiry date
has not passed. A token for a different product returns 403. A token whose signature does
not verify returns 401. An expired token returns 403 with a reason indicating the channel
has expired. The token format is described in full in [[crypto-license-sales-architecture]].
A token is `base64url(signature[64 bytes] || payload_json)` — an Ed25519 signature over
the payload bytes, prepended to the payload itself. The server splits the token, verifies
the signature against its stored public key, then checks the payload's product field
against the requested product and confirms the channel hasn't expired. A bad or malformed
signature returns 401; a valid signature for the wrong product, or an expired channel,
returns 403.

## Platform strings

Platform strings follow the Rust target triple convention. Examples include
`x86_64-unknown-linux-gnu` for 64-bit Linux on x86, `aarch64-unknown-linux-gnu` for
64-bit ARM Linux, and `x86_64-apple-darwin` for macOS on Intel. The server maps the
product name, version string, and platform triple directly to a file path in the releases
directory. If no binary has been built for the requested combination, the server returns
404 with a note that the build pipeline has not yet produced that release. The
latest-version redirect endpoint only redirects to platform strings for which a release
file actually exists.
Platform strings follow the Rust target triple convention — `x86_64-unknown-linux-gnu`,
`aarch64-unknown-linux-gnu`, `x86_64-apple-darwin`, and similar. The server maps product,
version, and platform directly to a file path in the releases directory; a combination
with no built binary returns 404. The latest-version redirect only targets platform
strings for which a release file actually exists.

## Key management and fail-safe behaviour

The server loads the public Ed25519 verification key at startup from a configuration
source. If no key is configured, the server does not silently accept all tokens: the
download and verification endpoints return a service-unavailable response. This fail-safe
behaviour means a misconfigured or freshly deployed instance that has not yet been given a
verification key will reject all requests rather than accidentally grant access. A correctly
configured instance with a valid key will accept tokens signed by the corresponding private
key and reject all others.
The server loads its public Ed25519 verification key at startup from configuration. If no
key is configured, it does not silently accept every token — the download and
introspection endpoints return 503 instead. A correctly configured instance accepts only
tokens signed by the corresponding private key.

## What the server does not do

The release server does not track individual downloads or maintain any download history.
It does not implement token revocation: once a token is issued, it remains valid until its
expiry date, and there is no revocation list. Customers who need to prevent a compromised
token from being used must wait for the token to expire; key rotation by the storefront
invalidates all previously issued tokens at the cost of requiring existing customers to
re-issue their tokens.

The server does not serve source code and does not act as a Git server. A stub endpoint
at the Git protocol path returns a redirect to the public GitHub repository rather than
proxying Git operations. This route is reserved for a future version that may offer
authenticated Git access to private repositories.
The Git protocol path is a stub: it returns a 503 with a pointer to the public GitHub
repository, not a live proxy and not an HTTP redirect — smart-HTTP Git access is not yet
enabled.

## See also