{"id":14967087,"url":"https://github.com/golemfactory/ya-runtime-http-auth","last_synced_at":"2026-02-28T04:11:48.541Z","repository":{"id":36964691,"uuid":"446388667","full_name":"golemfactory/ya-runtime-http-auth","owner":"golemfactory","description":"Generic HTTP authentication runtime for providing services on Golem network","archived":false,"fork":false,"pushed_at":"2022-11-18T10:15:11.000Z","size":274,"stargazers_count":2,"open_issues_count":2,"forks_count":4,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-10-19T19:12:33.138Z","etag":null,"topics":["golem","ya-runtime"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/golemfactory.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2022-01-10T11:05:03.000Z","updated_at":"2023-11-28T13:03:32.000Z","dependencies_parsed_at":"2023-01-17T09:04:01.510Z","dependency_job_id":null,"html_url":"https://github.com/golemfactory/ya-runtime-http-auth","commit_stats":null,"previous_names":[],"tags_count":19,"template":false,"template_full_name":null,"purl":"pkg:github/golemfactory/ya-runtime-http-auth","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/golemfactory%2Fya-runtime-http-auth","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/golemfactory%2Fya-runtime-http-auth/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/golemfactory%2Fya-runtime-http-auth/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/golemfactory%2Fya-runtime-http-auth/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/golemfactory","download_url":"https://codeload.github.com/golemfactory/ya-runtime-http-auth/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/golemfactory%2Fya-runtime-http-auth/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29924720,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-27T19:37:42.220Z","status":"online","status_checked_at":"2026-02-28T02:00:07.010Z","response_time":90,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["golem","ya-runtime"],"created_at":"2024-09-24T13:37:26.358Z","updated_at":"2026-02-28T04:11:48.526Z","avatar_url":"https://github.com/golemfactory.png","language":"Rust","readme":"# ya-runtime-http-auth\n\n`ya-runtime-http-auth` is a Yagna runtime binary for advertising HTTP-based services on the Golem Network.\n\n---\n\nQuick links:\n- [Overview](#overview)\n- [Runtime proposal document](https://github.com/golemfactory/golem-architecture/blob/7efb7fb7207980ba2dccb735e676f8436dcf18d8/gaps/gap-8_http_auth_runtime/gap-8_http_auth_runtime.md)\n- [Provider Agent - advertising a service](#provider-agent---advertising-a-service)\n- [Requestor Agent - overview](#requestor-agent---overview)\n- [Requestor Agent - example code using yapapi](https://github.com/golemfactory/yapapi/blob/mf/http-auth-example/examples/http-auth/http_auth.py)\n- [Self-signed certificates](#self-signed-certificates)\n\n---\n\n\n## Overview\n\n`ya-runtime-http-auth` serves as a gateway between the Golem Marketplace and an HTTP-based service accessible over\nthe Internet.\n\n```\n                                +-------------- Provider's machine --------------+\n+-----------+   Golem Network   | +----------+      +---------+      +---------+ |\n| Requestor | \u003c=================\u003e | Provider | \u003c--\u003e | ExeUnit | \u003c--\u003e | Runtime | |\n+-----------+                   | +----------+      +---------+      +---------+ |\n                                +------------------------------------------------+\n```\n\nAll HTTP requests to the service are routed via a custom reverse HTTP proxy implementation.\nThe proxy authorizes users and collects per-user, per-endpoint usage statistics.\nThese statistics will be used for billing purposes and sent to the Requestor.\n\nThe runtime binary is responsible for managing users authorized to use the service. Requestor's commands \nare translated into proxy's Management API calls, upon prior identity verification.\n\n```\n-------------- Provider's machine -----------+\n  +---------+   Management API   +---------+ |     Internet      +------+\n  | Runtime | \u003c----------------\u003e |  Proxy  | \u003c=================\u003e | User |\n  +---------+                    +---------+ |                   +------+\n                                     ||      |\n                                 +---------+ |\n                                 | Service | |\n                                 +---------+ |\n---------------------------------------------+                                                      \n\n```\n\nRuntime specification proposal can be found [here](https://github.com/golemfactory/golem-architecture/blob/7efb7fb7207980ba2dccb735e676f8436dcf18d8/gaps/gap-8_http_auth_runtime/gap-8_http_auth_runtime.md).\n\n---\n\n## Provider Agent - advertising a service\n\nAt the moment, it is required from the user to manually perform the setup steps below. \nThis process will be largely automated in the future.\n\n### Preparing your service\n\n1. Ensure that the service is listening on a local socket (a private IP address).\n\n2. Configure a daemon supervisor for your service. In case of a crash, it should be automatically restarted.\n\n3. The service needs to be running when advertised on the Golem Network.\n\nPlease note that if your HTTP service requires some additional authorization (e.g. user certificates), it may not be supported by\n`ya-runtime-http-auth` in the current version.\n\n### Installation\n\n1. `yagna`\n\n  In order to install yagna, please refer to this [handbook chapter](https://handbook.golem.network/provider-tutorials/provider-tutorial).\n\n2. `ya-runtime-http-auth`\n\n  Download and install the latest `deb` package from the [releases page](https://github.com/golemfactory/ya-runtime-http-auth/releases/latest).\n  You will find the installed runtime and proxy binaries at the `/usr/lib/yagna/plugins` directory.\n\n### Service definition\n\nService definition files contain basic information on the service and the configuration of the proxy HTTP server.\nThere can be multiple services exposed by a single server as long as they are configured with the distinct `from` endpoints.\n\nThe definition files are, by default, located at `~/.local/share/ya-runtime-http-auth/services`. \nCreate the path by typing the following command in a terminal:\n\n```bash\nmkdir -p ~/.local/share/ya-runtime-http-auth/services\n```\n\nNow, save this service definition file called `acme-service.json` at the newly created location:\n\n```json\n{\n  \"name\": \"acme-service\",\n  \"description\": \"ACME service v1.42\",\n  \"serverName\": [\"service.acme.com\", \"1.2.3.4\"],\n  \"bindHttps\": \"0.0.0.0:443\",\n  \"bindHttp\": \"0.0.0.0:80\",\n  \"from\": \"/acme\",\n  \"to\": \"http://127.0.0.1:10000\",\n  \"cert\": {\n    \"path\": \"/secure/acme/certs/server.cert\",\n    \"keyPath\": \"/secure/acme/certs/server.key\"\n  }\n}\n```\n\n- `name` - name of the service\n- `description` - extended service information\n- `serverName` - list of assigned domain names and / or public IP addresses\n- `bindHttps` - address to bind the HTTPS server to (required if `bindHttp` is not set)\n- `bindHttp` - address to bind the HTTP server to (required if `bindHttps` is not set)\n- `from` - source service endpoint. In this case, `service.acme.com/acme` or `1.2.3.4/acme`\n- `to` - service listening URL\n- `cert` - certificate and private key paths (required for HTTPS)\n\nIn this example, all requests from e.g. `https://1.2.3.4/acme/register` will be redirected to `http://127.0.0.1:10000/register`.\n\n**It's not recommended to use an HTTP-only proxy server for the service**. Unencrypted credentials sent by the users can\nbe captured by malicious actors in their local networks. Please create and use self-signed certificates when facing real-world \nusers. You might find the [following chapter](#self-signed-certificates) helpful.\n\n### Provider configuration\n\n### Runtime definition\n\nEach advertised service acts as a separate runtime and requires a new descriptor file, located at\n\na. `~/.local/lib/yagna/plugins` when using `golemsp`\nb. `/usr/lib/yagna/plugins` when running the `ya-provider` binary directly\n\nRuntime definition file's name needs to match the `ya-*.json` pattern to be discovered by the Provider Agent. In this case, \nthe file will be called `ya-runtime-acme.json` and contain the following:\n\n```json\n[\n  {\n    \"name\": \"acme-service\",\n    \"version\": \"0.1.0\",\n    \"supervisor-path\": \"exe-unit\",\n    \"runtime-path\": \"ya-runtime-http-auth/ya-runtime-http-auth\",\n    \"extra-args\": [\n      \"--runtime-managed-image\",\n      \"--runtime-arg\", \"acme-service\"\n    ],\n    \"config\": {\n    \t\"counters\": {\n    \t  \"http-auth.requests\": {\n            \"name\": \"requests\",\n            \"description\": \"Total number of HTTP requests\",\n            \"price\": true\n    \t  }\n    \t}\n    }\n  }\n]\n```\n\n- `name` - name of the service, advertised in the Golem Network\n- `version` - service version\n- `supervisor-path` - path to ExeUnit Supervisor, most often located in the same directory\n- `extra-args` - extra arguments passed to the ExeUnit Supervisor\n  - `--runtime-managed-image` - the Supervisor will not be responsible for downloading an image / payload to be executed by the Runtime\n  - `--runtime-arg acme-service` - the Runtime will look for a service definition file with a name set to `acme-service`\n- `config` -\u003e `counters`\n  - `http-auth.requests` - defines the service's HTTP request counter by `ya-runtime-http-auth`. `\"price\": true` \n    informs the Supervisor that this counter will be used in calculating the price. The counter only includes users\n    created by the current Requestor\n    \n### Billing configuration\n\nIn order to advertise the newly-created service in the Golem Network, a billing profile needs to be created. This can be\nachieved by editing the Provider Agent's presets file (`~/.local/share/ya-provider/presets.json`) to include the following:\n\n```json\n{\n  \"ver\": \"V1\",\n  \"active\": [\n    \"acme\"\n  ],\n  \"presets\": [\n    {\n      \"name\": \"acme\",\n      \"exeunit-name\": \"acme-service\",\n      \"pricing-model\": \"linear\",\n      \"initial-price\": 0,\n      \"usage-coeffs\": {\n        \"golem.usage.duration_sec\": 0.001,\n        \"golem.usage.cpu_sec\": 0.001,\n        \"http-auth.requests\": 0.00001\n      }\n    }\n  ]\n}\n```\n\nThis configuration file contains a single active preset called `acme`, defined for the runtime `acme-service`, \nas stated in the `ya-runtime-acme.json` definition file. Each HTTP call made by an authorized user will \ncost the Requestor 0.00001 GLM (or tGLM when running on the test network).\n\n### Starting the provider\n\nThe configuration process is complete. Start your provider by typing `golemsp run` in the terminal.\n\n## Requestor Agent - overview\n\n[This link](https://github.com/golemfactory/yapapi/blob/mf/http-auth-example/examples/http-auth/http_auth.py) will point you\nto the minimal implementation of an HTTP service advertised on Golem Marketplace.\n\nHowever, the real-world implementation would contain:\n- a custom market strategy that takes the HTTP request price into account\n- code to constrain the `golem.runtime.http-auth.https` property in the Offer to `true`.\n  This way Requestors enable their users to establish secure HTTPS connections with the service.\n- the `service info` command outputs a certificate hash, which should be used by clients to verify certificate's contents \n\n## Self-signed certificates\n\nIn most cases, a provider's machine won't be addressable by a domain name and their certificate won't be signed by a trusted authority.\nWhen the server presents a self-signed certificate, users will only be able to verify the embedded signature.\n\nHowever, the Requestor can equip each user with a certificate hash returned by the `service info` runtime command. \nEach user's HTTPS client may verify the certificate's hash, so that Man-in-the-Middle attacks can be prevented.\nThe client should ignore the missing Certificate Authority signature and the domain name included in the certificate.\n\n### Creating a self-signed certificate with OpenSSL\n\nCurrently application do not support keys encrypted with des. Use nodes options to generate unecrypted private key.\n\n```bash\nopenssl req -nodes -x509 -newkey rsa:4096 -keyout server.key -out server.cert -sha256 -days 3650\n```\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgolemfactory%2Fya-runtime-http-auth","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgolemfactory%2Fya-runtime-http-auth","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgolemfactory%2Fya-runtime-http-auth/lists"}