gcs-static-site-proxy 0.1.0__tar.gz

gcs_static_site_proxy-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,46 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  checks:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.14"]
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+
+      - name: Install uv and Python
+        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+        with:
+          version: "0.12.4"
+          python-version: ${{ matrix.python-version }}
+          enable-cache: true
+
+      - name: Install project
+        run: uv sync --locked --dev
+
+      - name: Test
+        run: uv run pytest -q
+
+      - name: Lint
+        run: uv run ruff check .
+
+      - name: Check formatting
+        run: uv run ruff format --check .
+
+      - name: Type-check
+        run: uv run ty check src tests
+
+      - name: Build distributions
+        run: uv build --no-sources

gcs_static_site_proxy-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,42 @@
+name: Publish release to PyPI
+
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: read
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+      contents: read
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+
+      - name: Install uv and Python
+        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+        with:
+          version: "0.12.4"
+          python-version: "3.14"
+
+      - name: Build distributions
+        run: uv build --no-sources
+
+      - name: Smoke-test wheel
+        run: >-
+          uv run --isolated --no-project --with ./dist/*.whl
+          gcs-static-site-proxy --version
+
+      - name: Smoke-test source distribution
+        run: >-
+          uv run --isolated --no-project --with ./dist/*.tar.gz
+          gcs-static-site-proxy --version
+
+      - name: Publish to PyPI
+        run: uv publish

gcs_static_site_proxy-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+.venv/
+.pytest_cache/
+.ruff_cache/
+__pycache__/
+*.py[cod]
+dist/

gcs_static_site_proxy-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alexei Ciobanu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

gcs_static_site_proxy-0.1.0/PKG-INFO

@@ -0,0 +1,217 @@
+Metadata-Version: 2.5
+Name: gcs-static-site-proxy
+Version: 0.1.0
+Summary: Serve private GCS static sites securely through a local proxy
+Project-URL: Documentation, https://github.com/alexei-ciobanu/gcs-static-site-proxy#readme
+Project-URL: Issues, https://github.com/alexei-ciobanu/gcs-static-site-proxy/issues
+Project-URL: Source, https://github.com/alexei-ciobanu/gcs-static-site-proxy
+Author: Alexei Ciobanu
+License-Expression: MIT
+License-File: LICENSE
+Keywords: gcs,google-cloud,proxy,static-site
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
+Requires-Python: >=3.11
+Requires-Dist: aiohttp<4,>=3.11
+Requires-Dist: google-auth[requests]<3,>=2.38
+Requires-Dist: truststore<1,>=0.10
+Description-Content-Type: text/markdown
+
+# gcs-static-site-proxy
+
+Serve one private Google Cloud Storage static-site prefix, or an explicit
+catalog of prefixes, through a renewable, read-only local proxy. The GCS bucket
+remains private: the proxy uses the operator's Application Default Credentials
+(ADC) and exposes only explicitly configured object prefixes.
+
+> **Status:** alpha. Review the publication-prefix and network-access security
+> model before using the proxy with protected data.
+
+## Requirements
+
+- Python 3.11 or newer
+- [`uv`](https://docs.astral.sh/uv/) for the recommended isolated invocation
+- Google Cloud CLI for initializing or refreshing ADC
+- `storage.objects.get` on the configured objects, normally through
+  `roles/storage.objectViewer` or a stronger role
+
+Initialize ADC:
+
+```bash
+gcloud auth login --update-adc
+```
+
+## Install and run on localhost
+
+Run the published package in an isolated environment:
+
+```bash
+uvx gcs-static-site-proxy@0.1.0 \
+  --bucket private-site-bucket \
+  --prefix team/sites/my-site
+```
+
+Alternatively, install it with `pip` and use either the command or Python
+module entry point:
+
+```bash
+python -m pip install gcs-static-site-proxy==0.1.0
+python -m gcs_static_site_proxy \
+  --bucket private-site-bucket \
+  --prefix team/sites/my-site
+```
+
+Run directly from a pinned public Git commit during development:
+
+```bash
+uvx --from 'git+https://github.com/alexei-ciobanu/gcs-static-site-proxy@COMMIT_SHA' \
+  gcs-static-site-proxy \
+  --bucket private-site-bucket \
+  --prefix team/sites/my-site
+```
+
+The default listener is `127.0.0.1:8080`. It accepts only `GET` and `HEAD`,
+rejects path traversal, and does not provide a general GCS proxy.
+Outbound authentication and GCS requests use the operating system trust store,
+including root certificate authorities installed through device management.
+
+## Multiple sites and a landing page
+
+Catalog mode serves a landing-page prefix at `/` and mounts explicitly
+allowlisted site prefixes under `/sites/<slug>/`:
+
+```bash
+uvx gcs-static-site-proxy@0.1.0 \
+  --bucket private-site-bucket \
+  --catalog-prefix team/publication/static-sites
+```
+
+The catalog prefix must contain this exact object:
+
+```text
+team/publication/static-sites/.gcs-static-site-proxy-sites.json
+```
+
+Example:
+
+```json
+{
+  "version": 1,
+  "sites": [
+    {
+      "slug": "service-review",
+      "title": "Service review",
+      "prefix": "team/projects/service-review/publication/site"
+    }
+  ]
+}
+```
+
+The landing page remains under the catalog prefix. Each mount maps only to its
+declared prefix; unknown slugs fail closed, and neither catalog nor site
+configuration objects are browser-accessible. Catalog editors can expose any
+prefix that their proxy operator can read, so treat the catalog as a browser
+publication allowlist and never mount a protected artifact prefix.
+
+The proxy loads and validates the catalog and every site's CSP at startup. The
+landing page uses the catalog prefix's `.gcs-static-site-proxy.json`; each
+mounted site uses the same well-known filename under its own prefix. Explicit
+CLI CSP overrides apply to all mounts.
+
+Path-mounted sites share a browser origin. Per-response CSPs remain distinct,
+but a script running in one mounted site can make same-origin requests to other
+mounted sites. Use one catalog only for sites approved for the same audience;
+use separate origins when stronger isolation is required.
+
+## Site security configuration
+
+Unless overridden, the proxy requests this exact object at startup:
+
+```text
+<prefix>/.gcs-static-site-proxy.json
+```
+
+Example:
+
+```json
+{
+  "version": 1,
+  "contentSecurityPolicy": "default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' data:; connect-src 'self'; object-src 'none'; base-uri 'none'; form-action 'none'; frame-ancestors 'none'"
+}
+```
+
+If it is absent, a strict built-in policy is used. An invalid or inaccessible
+configuration fails startup. The active source, generation and SHA-256 are
+printed.
+
+Without an explicit CLI mode, each prefix uses its own GCS configuration and
+falls back to the strict built-in policy when that object is absent. The
+mutually exclusive global modes are:
+
+- `--csp-override-file PATH` applies one exact local policy to every route;
+- `--strict-csp` applies the strict built-in policy to every route; and
+- `--no-csp` disables CSP on every route.
+
+In catalog mode these options affect the landing page and every mounted site.
+For a local override of only one site, run that prefix separately in
+single-site mode.
+
+`--no-csp` disables only CSP. The proxy continues to send `no-referrer`,
+`nosniff`, and frame-denial headers.
+
+## Network access
+
+Loopback is the safe default. Explicit non-loopback binding enables network
+mode:
+
+```bash
+uvx gcs-static-site-proxy@0.1.0 \
+  --bucket private-site-bucket \
+  --prefix team/sites/my-site \
+  --bind 0.0.0.0
+```
+
+Network mode generates a process-lifetime access token. Opening the printed
+tokenized URL exchanges it for an HttpOnly, SameSite session cookie. IP-literal
+Host values are accepted when they match the local destination address;
+machine hostnames are detected automatically. Use `--allow-host HOST` for an
+additional DNS alias.
+
+The cookie is intentionally a browser-session cookie rather than a persistent
+credential. If the browser is restarted while the proxy remains running, open
+the printed tokenized URL again.
+
+Anyone who has the token and can reach the listener can read the site using
+the operator's GCS permissions. Plain HTTP does not protect content from
+network interception. Supply both options for HTTPS:
+
+```bash
+--tls-cert certificate.pem --tls-key private-key.pem
+```
+
+Remote visitors cannot launch the local ADC reauthentication command.
+
+## Local development
+
+```bash
+uv sync --dev
+uv run pytest
+uv run ruff check .
+uv run ruff format --check .
+uv run ty check src
+uv build --no-sources
+```
+
+## License
+
+MIT

gcs_static_site_proxy-0.1.0/README.md

@@ -0,0 +1,188 @@
+# gcs-static-site-proxy
+
+Serve one private Google Cloud Storage static-site prefix, or an explicit
+catalog of prefixes, through a renewable, read-only local proxy. The GCS bucket
+remains private: the proxy uses the operator's Application Default Credentials
+(ADC) and exposes only explicitly configured object prefixes.
+
+> **Status:** alpha. Review the publication-prefix and network-access security
+> model before using the proxy with protected data.
+
+## Requirements
+
+- Python 3.11 or newer
+- [`uv`](https://docs.astral.sh/uv/) for the recommended isolated invocation
+- Google Cloud CLI for initializing or refreshing ADC
+- `storage.objects.get` on the configured objects, normally through
+  `roles/storage.objectViewer` or a stronger role
+
+Initialize ADC:
+
+```bash
+gcloud auth login --update-adc
+```
+
+## Install and run on localhost
+
+Run the published package in an isolated environment:
+
+```bash
+uvx gcs-static-site-proxy@0.1.0 \
+  --bucket private-site-bucket \
+  --prefix team/sites/my-site
+```
+
+Alternatively, install it with `pip` and use either the command or Python
+module entry point:
+
+```bash
+python -m pip install gcs-static-site-proxy==0.1.0
+python -m gcs_static_site_proxy \
+  --bucket private-site-bucket \
+  --prefix team/sites/my-site
+```
+
+Run directly from a pinned public Git commit during development:
+
+```bash
+uvx --from 'git+https://github.com/alexei-ciobanu/gcs-static-site-proxy@COMMIT_SHA' \
+  gcs-static-site-proxy \
+  --bucket private-site-bucket \
+  --prefix team/sites/my-site
+```
+
+The default listener is `127.0.0.1:8080`. It accepts only `GET` and `HEAD`,
+rejects path traversal, and does not provide a general GCS proxy.
+Outbound authentication and GCS requests use the operating system trust store,
+including root certificate authorities installed through device management.
+
+## Multiple sites and a landing page
+
+Catalog mode serves a landing-page prefix at `/` and mounts explicitly
+allowlisted site prefixes under `/sites/<slug>/`:
+
+```bash
+uvx gcs-static-site-proxy@0.1.0 \
+  --bucket private-site-bucket \
+  --catalog-prefix team/publication/static-sites
+```
+
+The catalog prefix must contain this exact object:
+
+```text
+team/publication/static-sites/.gcs-static-site-proxy-sites.json
+```
+
+Example:
+
+```json
+{
+  "version": 1,
+  "sites": [
+    {
+      "slug": "service-review",
+      "title": "Service review",
+      "prefix": "team/projects/service-review/publication/site"
+    }
+  ]
+}
+```
+
+The landing page remains under the catalog prefix. Each mount maps only to its
+declared prefix; unknown slugs fail closed, and neither catalog nor site
+configuration objects are browser-accessible. Catalog editors can expose any
+prefix that their proxy operator can read, so treat the catalog as a browser
+publication allowlist and never mount a protected artifact prefix.
+
+The proxy loads and validates the catalog and every site's CSP at startup. The
+landing page uses the catalog prefix's `.gcs-static-site-proxy.json`; each
+mounted site uses the same well-known filename under its own prefix. Explicit
+CLI CSP overrides apply to all mounts.
+
+Path-mounted sites share a browser origin. Per-response CSPs remain distinct,
+but a script running in one mounted site can make same-origin requests to other
+mounted sites. Use one catalog only for sites approved for the same audience;
+use separate origins when stronger isolation is required.
+
+## Site security configuration
+
+Unless overridden, the proxy requests this exact object at startup:
+
+```text
+<prefix>/.gcs-static-site-proxy.json
+```
+
+Example:
+
+```json
+{
+  "version": 1,
+  "contentSecurityPolicy": "default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' data:; connect-src 'self'; object-src 'none'; base-uri 'none'; form-action 'none'; frame-ancestors 'none'"
+}
+```
+
+If it is absent, a strict built-in policy is used. An invalid or inaccessible
+configuration fails startup. The active source, generation and SHA-256 are
+printed.
+
+Without an explicit CLI mode, each prefix uses its own GCS configuration and
+falls back to the strict built-in policy when that object is absent. The
+mutually exclusive global modes are:
+
+- `--csp-override-file PATH` applies one exact local policy to every route;
+- `--strict-csp` applies the strict built-in policy to every route; and
+- `--no-csp` disables CSP on every route.
+
+In catalog mode these options affect the landing page and every mounted site.
+For a local override of only one site, run that prefix separately in
+single-site mode.
+
+`--no-csp` disables only CSP. The proxy continues to send `no-referrer`,
+`nosniff`, and frame-denial headers.
+
+## Network access
+
+Loopback is the safe default. Explicit non-loopback binding enables network
+mode:
+
+```bash
+uvx gcs-static-site-proxy@0.1.0 \
+  --bucket private-site-bucket \
+  --prefix team/sites/my-site \
+  --bind 0.0.0.0
+```
+
+Network mode generates a process-lifetime access token. Opening the printed
+tokenized URL exchanges it for an HttpOnly, SameSite session cookie. IP-literal
+Host values are accepted when they match the local destination address;
+machine hostnames are detected automatically. Use `--allow-host HOST` for an
+additional DNS alias.
+
+The cookie is intentionally a browser-session cookie rather than a persistent
+credential. If the browser is restarted while the proxy remains running, open
+the printed tokenized URL again.
+
+Anyone who has the token and can reach the listener can read the site using
+the operator's GCS permissions. Plain HTTP does not protect content from
+network interception. Supply both options for HTTPS:
+
+```bash
+--tls-cert certificate.pem --tls-key private-key.pem
+```
+
+Remote visitors cannot launch the local ADC reauthentication command.
+
+## Local development
+
+```bash
+uv sync --dev
+uv run pytest
+uv run ruff check .
+uv run ruff format --check .
+uv run ty check src
+uv build --no-sources
+```
+
+## License
+
+MIT

gcs_static_site_proxy-0.1.0/pyproject.toml

@@ -0,0 +1,64 @@
+[build-system]
+requires = ["hatchling>=1.27,<2"]
+build-backend = "hatchling.build"
+
+[project]
+name = "gcs-static-site-proxy"
+version = "0.1.0"
+description = "Serve private GCS static sites securely through a local proxy"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+authors = [{ name = "Alexei Ciobanu" }]
+keywords = ["gcs", "google-cloud", "proxy", "static-site"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Environment :: Console",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: MacOS",
+  "Operating System :: Microsoft :: Windows",
+  "Operating System :: POSIX :: Linux",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Topic :: Internet :: WWW/HTTP :: HTTP Servers",
+]
+dependencies = [
+  "aiohttp>=3.11,<4",
+  "google-auth[requests]>=2.38,<3",
+  "truststore>=0.10,<1",
+]
+
+[project.urls]
+Documentation = "https://github.com/alexei-ciobanu/gcs-static-site-proxy#readme"
+Issues = "https://github.com/alexei-ciobanu/gcs-static-site-proxy/issues"
+Source = "https://github.com/alexei-ciobanu/gcs-static-site-proxy"
+
+[project.scripts]
+gcs-static-site-proxy = "gcs_static_site_proxy.cli:main"
+
+[dependency-groups]
+dev = [
+  "pytest>=8.3,<10",
+  "pytest-asyncio>=0.25,<2",
+  "ruff>=0.11,<1",
+  "ty>=0.0.1a20,<1",
+]
+
+[tool.uv]
+exclude-newer = "7 days"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/gcs_static_site_proxy"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+
+[tool.ruff]
+line-length = 88
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["ASYNC", "B", "E", "F", "I", "RUF", "SIM", "UP"]

gcs_static_site_proxy-0.1.0/src/gcs_static_site_proxy/__init__.py

@@ -0,0 +1,10 @@
+"""Renewable local proxy for a private GCS static-site prefix."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("gcs-static-site-proxy")
+except PackageNotFoundError:
+    __version__ = "0.0.0"
+
+__all__ = ["__version__"]

gcs_static_site_proxy-0.1.0/src/gcs_static_site_proxy/__main__.py

@@ -0,0 +1,4 @@
+from gcs_static_site_proxy.cli import main
+
+if __name__ == "__main__":
+    main()