Diff: services/private-git-paid-customer-endpoint.es
From 1c02ec1 to 1c02ec1
+0 / −0 lines
| Before | After |
|---|---|
| --- | --- |
| schema: foundry-doc-v1 | schema: foundry-doc-v1 |
| title: "Private Binary Download Endpoint for Paying Customers" | title: "Private Binary Download Endpoint for Paying Customers" |
| slug: private-git-paid-customer-endpoint | slug: private-git-paid-customer-endpoint |
| category: services | category: services |
| type: topic | type: topic |
| content_type: topic | content_type: topic |
| quality: complete | quality: complete |
| status: active | status: active |
| audience: vendor-public | audience: vendor-public |
| bcsc_class: no-disclosure-implication | bcsc_class: no-disclosure-implication |
| language_protocol: PROSE-TOPIC | language_protocol: PROSE-TOPIC |
| last_edited: 2026-06-13 | last_edited: 2026-06-13 |
| editor: pointsav-engineering | editor: pointsav-engineering |
| paired_with: private-git-paid-customer-endpoint.es.md | 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 by design — it holds no payment records, no customer data, and no signing keys." | short_description: "The binary release server behind software.pointsav.com verifies Ed25519 license tokens and streams compiled binaries. Stateless by design — it holds no payment records, no customer data, and no signing keys." |
| cites: [] | cites: [] |
| --- | --- |
| The binary release server is the component of `software.pointsav.com` that delivers | The binary release server is the component of `software.pointsav.com` that delivers |
| compiled binaries to paying customers. It is a thin, stateless gate: it holds no payment | 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 | 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 | 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 | 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 | download the corresponding binary without any further interaction with the payment |
| infrastructure. | infrastructure. |
| ## Route structure | ## Route structure |
| The release server organises its endpoints into four categories. | The release server organises its endpoints into four categories. |
| **Product and version discovery.** An unauthenticated product index lists all products | **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 | 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 | 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. | for consumption by tooling such as package managers, installer scripts, and CI pipelines. |
| **Versioned binary download.** The primary gated endpoint serves a binary for a specific | **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. | 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 | 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 | and is always unauthenticated — detached signatures are public by design, allowing any |
| party to verify the authenticity of a binary without holding a license. | party to verify the authenticity of a binary without holding a license. |
| **Latest-version redirect.** A convenience endpoint resolves the highest available version | **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 | 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 | 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 | version combinations for which a release actually exists; it will not redirect to a version |
| that lacks a binary for the requested platform. | that lacks a binary for the requested platform. |
| **Release manifest.** A per-version metadata endpoint serves a structured manifest | **Release manifest.** A per-version metadata endpoint serves a structured manifest |
| describing the contents of a release. No authentication is required. This endpoint is | 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 | useful for tooling that needs to inspect what a release contains before initiating a |
| download. | download. |
| ## Authentication | ## Authentication |
| The release server accepts a license token in two forms. | The release server accepts a license token in two forms. |
| **HTTP Authorization header.** The token is passed as a Bearer credential in the | **HTTP Authorization header.** The token is passed as a Bearer credential in the |
| `Authorization` header. This is the standard form for programmatic clients, automated | `Authorization` header. This is the standard form for programmatic clients, automated |
| installers, and command-line tools that can set arbitrary request headers. | 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. | **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 | 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 | 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 | 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 | equally secure — neither exposes the token to additional parties beyond the client and |
| the server. | the server. |
| ## Verification logic | ## Verification logic |
| The server decodes the base64url token string, splits off the first 64 bytes as an Ed25519 | 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 | 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 | 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 | 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 | 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 | 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]]. | has expired. The token format is described in full in [[crypto-license-sales-architecture]]. |
| ## Platform strings | ## Platform strings |
| Platform strings follow the Rust target triple convention. Examples include | 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 | `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 | 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 | 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 | 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 | 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 | latest-version redirect endpoint only redirects to platform strings for which a release |
| file actually exists. | file actually exists. |
| ## Key management and fail-safe behaviour | ## Key management and fail-safe behaviour |
| The server loads the public Ed25519 verification key at startup from a configuration | 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 | 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 | 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 | 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 | 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 | configured instance with a valid key will accept tokens signed by the corresponding private |
| key and reject all others. | key and reject all others. |
| ## What the server does not do | ## What the server does not do |
| The release server does not track individual downloads or maintain any download history. | 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 | 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 | 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 | 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 | invalidates all previously issued tokens at the cost of requiring existing customers to |
| re-issue their tokens. | re-issue their tokens. |
| The server does not serve source code and does not act as a Git server. A stub endpoint | 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 | 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 | proxying Git operations. This route is reserved for a future version that may offer |
| authenticated Git access to private repositories. | authenticated Git access to private repositories. |
| ## See also | ## See also |
| - [[crypto-license-sales-architecture]] — how payments are processed and tokens are issued upstream of this server | - [[crypto-license-sales-architecture]] — how payments are processed and tokens are issued upstream of this server |
| - [[software-distribution-substrate]] — overview of the three-component system this server belongs to | - [[software-distribution-substrate]] — overview of the three-component system this server belongs to |
| - [[authenticate-binary-downloads]] — step-by-step guide: verify Ed25519-signed binary releases from the private distribution endpoint | - [[authenticate-binary-downloads]] — step-by-step guide: verify Ed25519-signed binary releases from the private distribution endpoint |
| - [[issue-capability-token]] — step-by-step guide: generate a scoped Ed25519 capability token for a device or service | - [[issue-capability-token]] — step-by-step guide: generate a scoped Ed25519 capability token for a device or service |