{"id":19952871,"url":"https://github.com/ethersphere/gateway-proxy","last_synced_at":"2025-05-03T19:31:00.759Z","repository":{"id":37951700,"uuid":"420937187","full_name":"ethersphere/gateway-proxy","owner":"ethersphere","description":"Proxy service for the Bee client","archived":false,"fork":false,"pushed_at":"2025-03-25T14:10:52.000Z","size":1263,"stargazers_count":11,"open_issues_count":54,"forks_count":6,"subscribers_count":6,"default_branch":"master","last_synced_at":"2025-04-07T20:21:23.739Z","etag":null,"topics":["bee","decentralized","proxy","storage","swarm","typescript"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ethersphere.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-10-25T08:20:58.000Z","updated_at":"2024-08-28T13:47:00.000Z","dependencies_parsed_at":"2023-02-16T19:16:11.626Z","dependency_job_id":"3d0f901a-9af6-44a5-ac7c-b852218b8307","html_url":"https://github.com/ethersphere/gateway-proxy","commit_stats":null,"previous_names":[],"tags_count":22,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ethersphere%2Fgateway-proxy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ethersphere%2Fgateway-proxy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ethersphere%2Fgateway-proxy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ethersphere%2Fgateway-proxy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ethersphere","download_url":"https://codeload.github.com/ethersphere/gateway-proxy/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252241956,"owners_count":21717077,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["bee","decentralized","proxy","storage","swarm","typescript"],"created_at":"2024-11-13T01:14:38.365Z","updated_at":"2025-05-03T19:31:00.266Z","avatar_url":"https://github.com/ethersphere.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# gateway-proxy\n\n[![Tests](https://github.com/ethersphere/gateway-proxy/actions/workflows/tests.yaml/badge.svg)](https://github.com/ethersphere/gateway-proxy/actions/workflows/tests.yaml)\n[![Dependency Status](https://david-dm.org/ethersphere/gateway-proxy.svg?style=flat-square)](https://david-dm.org/ethersphere/gateway-proxy)\n[![FOSSA Status](https://app.fossa.com/api/projects/git%2Bgithub.com%2Fethersphere%2Fgateway-proxy.svg?type=shield)](https://app.fossa.com/projects/git%2Bgithub.com%2Fethersphere%2Fgateway-proxy?ref=badge_shield)\n[![](https://img.shields.io/badge/made%20by-Swarm-blue.svg?style=flat-square)](https://swarm.ethereum.org/)\n[![standard-readme compliant](https://img.shields.io/badge/standard--readme-OK-brightgreen.svg?style=flat-square)](https://github.com/RichardLitt/standard-readme)\n[![js-standard-style](https://img.shields.io/badge/code%20style-standard-brightgreen.svg?style=flat-square)](https://github.com/feross/standard)\n![](https://img.shields.io/badge/npm-%3E%3D6.0.0-orange.svg?style=flat-square)\n![](https://img.shields.io/badge/Node.js-%3E%3D12.0.0-orange.svg?style=flat-square)\n\n\u003e Proxy to you bee node which aims to work as a public or personal gateway or to be used in CI for uploading to Swarm.\n\n**Warning: This project is in beta state. There might (and most probably will) be changes in the future to its API and\nworking. Also, no guarantees can be made about its stability, efficiency, and security at this stage.**\n\nThis project is intended to be used with\n**Bee\u0026nbsp;version\u0026nbsp;\u003c!-- SUPPORTED_BEE_START --\u003e1.7.0-bbf13011\u003c!-- SUPPORTED_BEE_END --\u003e**. Using it with older or\nnewer Bee versions is not recommended and may not work. Stay up to date by joining the\n[official Discord](https://discord.gg/GU22h2utj6) and by keeping an eye on the\n[releases tab](https://github.com/ethersphere/gateway-proxy/releases).\n\n## Table of Contents\n\n- [Install](#install)\n- [Usage](#usage)\n  - [Bzz.link support](#bzzlink-support)\n  - [Examples](#examples)\n    - [1. No postage stamp](#1-no-postage-stamp)\n    - [2. Hardcoded postage stamp](#2-hardcoded-postage-stamp)\n    - [3. Autobuy postage stamps](#3-autobuy-postage-stamps)\n    - [4. Extends stamps TTL](#4-extends-stamps-ttl)\n    - [Enable authentication](#enable-authentication)\n  - [Environment variables](#environment-variables)\n  - [Curl](#curl)\n- [API](#api)\n- [Maintainers](#maintainers)\n- [License](#license)\n\n## Install\n\n```sh\ngit clone https://github.com/ethersphere/gateway-proxy.git\ncd gateway-proxy\n```\n\n## Usage\n\nThe proxy can manage postage stamps for you in 4 modes of operation:\n\n1. It can just proxy requests without manipulating the request\n2. It can add/replace the request postage stamp with one provided through environment variable `POSTAGE_STAMP`\n3. It can add/replace the request postage stamp with an auto-bought stamp or existing stamp that fulfils the amount,\n   depth and is not too full or about to expire. To enable this, provide at minimum `POSTAGE_DEPTH` and\n   `POSTAGE_AMOUNT`.\n4. It can extend the TTL of a stamp that is about to expire. To enable this, set `POSTAGE_EXTENDSTTL=true`, provide\n   `POSTAGE_AMOUNT`, `POSTAGE_DEPTH` with the desired amount to use and `POSTAGE_TTL_MIN` above with a number above or\n   equal to 60.\n\nIn modes 1, 2 and 3, the proxy can be configured to require authentication secret to forward the requests. Use the\n`AUTH_SECRET` environment variable to enable it.\n\n### Bzz.link support\n\nGateway proxy has support for Bzz.link which allows translating\n[Swarm CIDs](https://github.com/ethersphere/swarm-cid-js) and ENS names placed under subdomains into `/bzz` call. This\nallows to have better security model for your web applications.\n\nIn order to use Bzz.link, set the `HOSTNAME` environment variable, and either or both of `CID_SUBDOMAINS` and\n`ENS_SUBDOMAINS` according to your requirements. You may also need to set up DNS with wildcard subdomain support.\n\n### Reupload pinned content\n\nIt can reupload existing pinned content that appear as not retrievable. To enable this, provide `REAUPLOAD_PERIOD` with\nthe miliseconds that represent the time to periodicaly check pinned content status.\n\n### Examples\n\n#### 1. No postage stamp\n\n```sh\nnpm run start\n```\n\n#### 2. Hardcoded postage stamp\n\n```sh\nexport POSTAGE_STAMP=f1e4ff753ea1cb923269ed0cda909d13a10d624719edf261e196584e9e764e50\n\nnpm run start\n```\n\n#### 3. Autobuy postage stamps\n\n```sh\nexport POSTAGE_DEPTH=20\nexport POSTAGE_AMOUNT=414720000\nexport POSTAGE_TTL_MIN=60\n\nnpm run start\n```\n\n#### 4. Extends stamps TTL\n\n```sh\nexport POSTAGE_EXTENDSTTL=true\nexport POSTAGE_TTL_MIN=60\nexport POSTAGE_DEPTH=20\nexport POSTAGE_AMOUNT=414720000\n\nnpm run start\n```\n\n#### Reupload pinned content\n\n```sh\nexport REUPLOAD_PERIOD=30000\n\nnpm run start\n```\n\n#### Enable authentication\n\n```sh\nexport AUTH_SECRET=\"this_is_some_secret_string\"\n\nnpm run start\n```\n\n### Environment variables\n\n| Name                    | Default Value                                                    | Description                                                                                                                                                                 |\n| ----------------------- | ---------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| BEE_API_URL             | http://localhost:1633                                            | URL of the Bee node API                                                                                                                                                     |\n| AUTH_SECRET             | undefined                                                        | Authentication secret, disabled if not set (this secret is checked in the request header `authorization`).                                                                  |\n| SOFT_AUTH               | false                                                            | Only POST requests require authentication.                                                                                                                                  |\n| HOSTNAME                | localhost                                                        | Hostname of the proxy. Required for Bzz.link support.                                                                                                                       |\n| PORT                    | 3000                                                             | Port of the proxy.                                                                                                                                                          |\n| POSTAGE_STAMP           | undefined                                                        | Postage stamp that should be used for all upload requests. If provided, the autobuy feature is disabled.                                                                    |\n| POSTAGE_DEPTH           | undefined                                                        | Postage stamp depth to be used when buying new stamps or selecting existing stamps.                                                                                         |\n| POSTAGE_AMOUNT          | undefined                                                        | Postage stamp amount to be used when buying new stamps or selecting existing stamps.                                                                                        |\n| POSTAGE_USAGE_THRESHOLD | 0.7                                                              | Usage percentage at which new postage stamp will be bought (value between 0 and 1).                                                                                         |\n| POSTAGE_USAGE_MAX       | 0.9                                                              | Usage percentage at which existing postage stamp should not be considered viable ( values 0 to 1).                                                                          |\n| POSTAGE_TTL_MIN         | `autobuy`: 5 \\* POSTAGE_REFRESH_PERIOD. `extends TTL`: undefined | In `autobuy`, Minimal time to live for the postage stamps to still be considered for upload (in seconds). In `extends TTL` is mandatory and required to be above 60 seconds |\n| POSTAGE_REFRESH_PERIOD  | 60                                                               | How frequently are the postage stamps checked in seconds.                                                                                                                   |\n| CID_SUBDOMAINS          | false                                                            | Enables Bzz.link subdomain translation functionality for CIDs.                                                                                                              |\n| ENS_SUBDOMAINS          | false                                                            | Enables Bzz.link subdomain translation functionality for ENS.                                                                                                               |\n| REMOVE_PIN_HEADER       | true                                                             | Removes swarm-pin header on all proxy requests.                                                                                                                             |\n| `LOG_LEVEL`             | info                                                             | Log level that is outputted (values: `critical`, `error`, `warn`, `info`, `verbose`, `debug`)                                                                               |\n| POSTAGE_EXTENDSTTL      | false                                                            | Enables extends TTL feature. Works along with POSTAGE_AMOUNT                                                                                                                |\n| EXPOSE_HASHED_IDENTITY  | false                                                            | Exposes `x-bee-node` header, which is the hashed identity of the Bee node for identification purposes                                                                       |\n| REUPLOAD_PERIOD         | undefined                                                        | How frequently are the pinned content checked to be reuploaded.                                                                                                             |\n| HOMEPAGE                | undefined                                                        | Swarm hash that loads as the homepage of gateway-proxy                                                                                                                      |\n| REMAP                   | undefined                                                        | Semicolon separated `name=hash` values to rewrite Swarm hashes to human-friendly names                                                                                      |\n| ALLOWLIST               | undefined                                                        | Comma separated list of hashes, ENS domains or CIDs to allow                                                                                                                |\n| ALLOW_USER_AGENTS       | undefined                                                        | Comma separated list of user-agent substrings to give unlimited access to                                                                                                   |\n| POST_SIZE_LIMIT         | 1gb                                                              | Maximum size of the POST request body in bytes.                                                                                                                             |\n\n### Curl\n\nUpload a file\n\n```sh\ncurl \\\n  -X POST http://localhost:3000/bzz \\\n  -H \"Accept: application/json, text/plain, */*\" \\\n  -H \"Content-Type: application/x-www-form-urlencoded\" \\\n  -H \"swarm-postage-batch-id: f1e4ff753ea1cb923269ed0cda909d13a10d624719edf261e196584e9e764e50\" \\\n  -H \"authorization: this_is_some_secret_string\"\n```\n\n```sh\n{\"reference\":\"a30e9c3ecbe68450924b20a7d46f745fa04289f7381826bdd51289aee4ad32f6\"}\n```\n\nDownload\n\n```sh\ncurl \\\n  -L http://localhost:3000/bzz/a30e9c3ecbe68450924b20a7d46f745fa04289f7381826bdd51289aee4ad32f6 \\\n  -H \"authorization: this_is_some_secret_string\" \\\n  --output -\n```\n\n## API\n\n| Endpoint                    | Response code     | Response text                                                                                                           |\n| --------------------------- | ----------------- | ----------------------------------------------------------------------------------------------------------------------- |\n| `GET /health`               | `200`             | `OK`                                                                                                                    |\n|                             | `403`             | `Forbidden`                                                                                                             |\n| `GET /readiness`            | `200`             | `OK`                                                                                                                    |\n|                             | `403`             | `Forbidden`                                                                                                             |\n|                             | `502`             | `Bad Gateway` when can not connect to Bee node                                                                          |\n| `GET /bzz/:swarmhash`       | `200`, `403`, ... | See official [bee documentation](https://docs.ethswarm.org/api/#tag/BZZ/paths/~1bzz~1{reference}/get)                   |\n| `POST /bzz`                 | `201`, `403`, ... | See official [bee documentation](https://docs.ethswarm.org/api/#tag/BZZ/paths/~1bzz/post)                               |\n| `GET /bytes/:swarmhash`     | `200`, `403`, ... | See official [bee documentation](https://docs.ethswarm.org/api/#tag/Bytes/paths/~1bytes~1{reference}/get)               |\n| `POST /bytes`               | `201`, `403`, ... | See official [bee documentation](https://docs.ethswarm.org/api/#tag/Bytes/paths/~1bytes/post)                           |\n| `GET /chunks/:swarmhash`    | `200`, `403`, ... | See official [bee documentation](https://docs.ethswarm.org/api/#tag/Chunk/paths/~1chunks~1{reference}/get)              |\n| `POST /chunks`              | `201`, `403`, ... | See official [bee documentation](https://docs.ethswarm.org/api/#tag/Chunk/paths/~1chunks/post)                          |\n| `POST /soc/:owner/:id`      | `201`, `403`, ... | See official [bee documentation](https://docs.ethswarm.org/api/#tag/Single-owner-chunk/paths/~1soc~1{owner}~1{id}/post) |\n| `GET /feeds/:owner/:topic`  | `200`, `403`, ... | See official [bee documentation](https://docs.ethswarm.org/api/#tag/Feed/paths/~1feeds~1{owner}~1{topic}/get)           |\n| `POST /feeds/:owner/:topic` | `201`, `403`, ... | See official [bee documentation](https://docs.ethswarm.org/api/#tag/Feed/paths/~1feeds~1{owner}~1{topic}/post)          |\n\n## Contribute\n\nThere are some ways you can make this module better:\n\n- Consult our [open issues](https://github.com/ethersphere/gateway-proxy/issues) and take on one of them\n- Help our tests reach 100% coverage!\n- Join us in our [Discord chat](https://discord.gg/wdghaQsGq5) in the #develop-on-swarm channel if you have questions or\n  want to give feedback\n\n### Local development with Bzz.link\n\nLocal development with the subdomain Bzz.link support is a bit more tricky as it requires to have a way how to direct\nlocal subdomains to given URL.\n\nEasy way is to have one testing CID that you will put directly to `/etc/hosts` and use only that for testing.\n\n```\nbah5acgzamh5fl7emnrazttpy7sag6utq5myidv3venspn6l5sevr4lko2n3q.localhost 127.0.0.1\n```\n\nIf you want fully functional setup than you have to locally install some DNS client that will provide you this\nfunctionality. See for example [here](https://serverfault.com/a/118589) for `dnsmasq` solution.\n\n## Maintainers\n\n- [Cafe137](https://github.com/Cafe137)\n\n## License\n\n[BSD-3-Clause](./LICENSE)\n\n[![FOSSA Status](https://app.fossa.com/api/projects/git%2Bgithub.com%2Fethersphere%2Fgateway-proxy.svg?type=large)](https://app.fossa.com/projects/git%2Bgithub.com%2Fethersphere%2Fgateway-proxy?ref=badge_large)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fethersphere%2Fgateway-proxy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fethersphere%2Fgateway-proxy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fethersphere%2Fgateway-proxy/lists"}