Generalize reverse proxy source allowlist

- 이후 리뉴얼 때 큰 카드로 사용

.env.example

@@ -0,0 +1,16 @@
+IMAGE_BIND_ADDRESS=0.0.0.0
+IMAGE_PORT=8191
+IMAGE_REPOSITORY_PATH=/home/letrhee/sam_rebuild/image
+IMAGE_UID=1000
+IMAGE_GID=1000
+# Comma- or space-separated source CIDRs of hosts that reverse-proxy to port 8191.
+TRUSTED_PROXY_CIDRS=172.30.1.75/32
+
+IMAGE_REMOTE_URL=https://gitea.hided.net/devsam/image.git
+IMAGE_REPOSITORY_FULL_NAME=devsam/image
+IMAGE_DEFAULT_BRANCH=master
+IMAGE_ALLOWED_BRANCHES=master
+IMAGE_PUBLIC_BASES=https://sam.hided.net/image,https://sam-image.hided.net
+
+GITEA_WEBHOOK_SECRET_FILE=./secrets/gitea_webhook_secret
+IMAGE_ADMIN_SECRET_FILE=./secrets/image_admin_secret

.gitignore

@@ -0,0 +1,10 @@
+/hook/gogs_key.php
+/hook/logs.txt
+/hook/list.json
+/hook/HashKey.php
+/hook/legacy-enabled
+/hook/inventory.v2.json
+/.env
+/secrets/*
+!/secrets/.gitkeep
+/runtime-data/

README.md

@@ -0,0 +1,129 @@
+# Shared image repository
+
+`icons/` is served as `/image/icons/`. General portraits follow these rules:
+
+- `icons/장수/<장수명>.<확장자>` is the canonical shared path.
+- Scenario-specific collections keep a separate directory such as
+  `icons/걸그룹/` or `icons/롤시나리오/`.
+- Root-level numeric files such as `icons/1047.jpg` are compatibility aliases
+  for deployed legacy versions. Do not delete or replace them while those
+  versions are in service.
+- A general name must map to one canonical file. If two records intentionally
+  need different portraits, disambiguate the scenario name or use an explicit
+  scenario-specific path.
+
+The core2026 repository owns `resources/general-icons.json` and
+`tools/manage-general-icons.mjs`. Use that tool with this repository as
+`--image-root` to synchronize aliases, scenario paths, and verify that every
+catalog source exists and has identical bytes.
+
+## Public URLs
+
+The same tracked files are exposed through both URL contracts:
+
+- `https://sam.hided.net/image/game/...` and `/image/icons/...`
+- `https://sam-image.hided.net/game/...` and `/icons/...`
+- `https://sam-image.hided.net/image/...` is a compatibility alias.
+
+Do not redirect the old `/image/*` URLs to the dedicated domain. Existing PHP
+and core2026 clients use same-origin relative paths and can move independently.
+The image server never exposes the repository root, `.git`, PHP sources, or
+directory listings.
+
+## Node webhook deployment service
+
+`compose.yaml` runs a read-only Nginx static edge and an internal Node service.
+Only the edge publishes port 8191. The Node service verifies the raw Gitea
+`X-Gitea-Signature`, accepts push events for `devsam/image`, fetches the exact
+remote branch tip, rejects dirty or non-fast-forward updates, and serializes all
+Git changes. The initial and only allowed branch is `master` unless
+`IMAGE_ALLOWED_BRANCHES` is explicitly expanded.
+
+The service is reverse-proxy agnostic. Its current reverse proxy happens to
+reach this server from `172.30.1.75`, but Caddy, Nginx, HAProxy, or another
+proxy can be used. Keep every observed proxy source CIDR in the untracked
+`TRUSTED_PROXY_CIDRS` value, separated by commas or spaces, and re-check the
+value whenever proxy networking changes. The published port binds all server
+interfaces, so production also needs a host `DOCKER-USER` (or equivalent)
+firewall rule allowing those source CIDRs to TCP 8191 and rejecting other
+sources. The static Nginx edge applies the same source allowlist.
+
+### Prepare
+
+```sh
+cp .env.example .env
+./deploy/scripts/init-secrets.sh
+docker compose config --quiet
+docker compose build
+```
+
+Apply and inspect the dedicated Docker ingress chain with root privileges:
+
+```sh
+sudo env TRUSTED_PROXY_CIDRS=172.30.1.75/32 IMAGE_PORT=8191 \
+  ./deploy/scripts/firewall-8191.sh apply
+sudo ./deploy/scripts/firewall-8191.sh check
+```
+
+The script only owns the `SAM_IMAGE_INGRESS` chain and its port-8191 jump from
+`DOCKER-USER`; it does not flush shared firewall chains.
+
+Secret values are generated under ignored `secrets/` files with mode 0600 and
+are never printed. Put the contents of `secrets/gitea_webhook_secret` into the
+Gitea webhook configuration. Configure a JSON push webhook targeting:
+
+```text
+https://sam-image.hided.net/v1/hooks/gitea
+```
+
+Use branch filter `master`. Disable the old PHP webhook before enabling the new
+writer. The legacy PHP files remain in `hook/` for an explicit rollback, but
+PHP and Node must never mutate the checkout concurrently.
+
+Legacy HTTP mutation is disabled by default. An emergency PHP rollback must
+first stop `image-hook`, then create the ignored `hook/legacy-enabled` sentinel
+in the legacy checkout before restoring its Caddy/Gitea route. Remove the
+sentinel before Node is started again. CLI execution of `hook/git_pull.php`
+from the `hook/` directory remains available for local recovery without
+exposing the HTTP endpoint.
+
+### Start and verify
+
+```sh
+docker compose up -d --build
+docker compose ps
+curl -fsS https://sam-image.hided.net/healthz
+curl -fsS https://sam-image.hided.net/v1/status
+curl -fsS https://sam-image.hided.net/game/back.jpg -o /dev/null
+curl -fsS https://sam-image.hided.net/image/icons/default.jpg -o /dev/null
+```
+
+Nginx serves only `game/`, `icons/`, `hook/list.json`, and
+`hook/inventory.v2.json`. The API inventory additionally reports the deployed
+branch, full commit, generation time, asset list, and both public base URLs.
+
+### Explicit branch deployment
+
+Automatic pushes only update the active branch. Add a branch to
+`IMAGE_ALLOWED_BRANCHES`, recreate `image-hook`, and switch it with the internal
+signed administration command:
+
+```sh
+./deploy/scripts/admin-deploy.sh <branch> [expected-commit]
+```
+
+The administration route is not exposed through the public reverse proxy.
+
+### Tests and rollback
+
+```sh
+docker build -t sam-image-hook:test node-hook
+docker run --rm sam-image-hook:test npm test
+docker compose exec -T image-web nginx -t -c /tmp/nginx.conf
+```
+
+Stopping `image-hook` does not remove the last checked-out files from the
+static service. For a full rollback, stop Node mutation first, restore the old
+Caddy/PHP webhook route, and only then enable the legacy writer. Preserve both
+checkouts until public file hashes and representative browser requests have
+been verified.

compose.yaml

@@ -0,0 +1,90 @@
+name: sam-image
+
+services:
+  image-hook:
+    build:
+      context: ./node-hook
+    image: sam-image-hook:1.0.0
+    restart: unless-stopped
+    user: "${IMAGE_UID:-1000}:${IMAGE_GID:-1000}"
+    read_only: true
+    init: true
+    environment:
+      PORT: "8081"
+      IMAGE_REPOSITORY_PATH: /data/image
+      IMAGE_REMOTE_URL: ${IMAGE_REMOTE_URL:-https://gitea.hided.net/devsam/image.git}
+      IMAGE_REPOSITORY_FULL_NAME: ${IMAGE_REPOSITORY_FULL_NAME:-devsam/image}
+      IMAGE_DEFAULT_BRANCH: ${IMAGE_DEFAULT_BRANCH:-master}
+      IMAGE_ALLOWED_BRANCHES: ${IMAGE_ALLOWED_BRANCHES:-master}
+      IMAGE_PUBLIC_BASES: ${IMAGE_PUBLIC_BASES:-https://sam.hided.net/image,https://sam-image.hided.net}
+      IMAGE_STATE_PATH: /var/lib/image-hook/state.json
+      GITEA_WEBHOOK_SECRET_FILE: /run/secrets/gitea_webhook_secret
+      IMAGE_ADMIN_SECRET_FILE: /run/secrets/image_admin_secret
+    volumes:
+      - type: bind
+        source: ${IMAGE_REPOSITORY_PATH:-.}
+        target: /data/image
+      - ./runtime-data:/var/lib/image-hook
+    secrets:
+      - gitea_webhook_secret
+      - image_admin_secret
+    tmpfs:
+      - /tmp:size=16m,mode=1777
+    cap_drop: [ALL]
+    security_opt:
+      - no-new-privileges:true
+    pids_limit: 64
+    mem_limit: 256m
+    cpus: 1.0
+    healthcheck:
+      test: [CMD, node, -e, "fetch('http://127.0.0.1:8081/healthz').then(r=>{if(!r.ok)process.exit(1)}).catch(()=>process.exit(1))"]
+      interval: 10s
+      timeout: 3s
+      retries: 6
+      start_period: 10s
+    networks: [image-internal, image-egress]
+
+  image-web:
+    build:
+      context: ./deploy/nginx
+    image: sam-image-web:1.0.0
+    restart: unless-stopped
+    depends_on:
+      image-hook:
+        condition: service_healthy
+    read_only: true
+    environment:
+      TRUSTED_PROXY_CIDRS: ${TRUSTED_PROXY_CIDRS:?Set TRUSTED_PROXY_CIDRS to the direct reverse-proxy source CIDR list}
+    ports:
+      - "${IMAGE_BIND_ADDRESS:-0.0.0.0}:${IMAGE_PORT:-8191}:8080"
+    volumes:
+      - type: bind
+        source: ${IMAGE_REPOSITORY_PATH:-.}
+        target: /srv/image
+        read_only: true
+    tmpfs:
+      - /tmp:size=8m,mode=1777
+    cap_drop: [ALL]
+    security_opt:
+      - no-new-privileges:true
+    pids_limit: 32
+    mem_limit: 64m
+    cpus: 0.5
+    healthcheck:
+      test: [CMD, wget, -q, -O, /dev/null, http://127.0.0.1:8080/healthz]
+      interval: 10s
+      timeout: 3s
+      retries: 6
+    networks: [image-internal, image-edge]
+
+networks:
+  image-internal:
+    internal: true
+  image-egress:
+  image-edge:
+
+secrets:
+  gitea_webhook_secret:
+    file: ${GITEA_WEBHOOK_SECRET_FILE:-./secrets/gitea_webhook_secret}
+  image_admin_secret:
+    file: ${IMAGE_ADMIN_SECRET_FILE:-./secrets/image_admin_secret}

deploy/nginx/Dockerfile

@@ -0,0 +1,9 @@
+FROM nginx:1.29.5-alpine@sha256:1eff5a5f3fcf8431a0abb7eddf5471fec24e5e1905a2581aeacdb07a4479b92b
+
+COPY templates/default.conf.template /etc/image/default.conf.template
+COPY entrypoint.sh /usr/local/bin/image-web-entrypoint
+RUN chmod 0555 /usr/local/bin/image-web-entrypoint
+
+USER nginx
+EXPOSE 8080
+ENTRYPOINT ["/usr/local/bin/image-web-entrypoint"]

deploy/nginx/entrypoint.sh

@@ -0,0 +1,29 @@
+#!/bin/sh
+set -eu
+
+trusted_proxy_cidrs=${TRUSTED_PROXY_CIDRS:-${CADDY_SOURCE_CIDR:-}}
+
+if [ -z "$trusted_proxy_cidrs" ]; then
+    echo "TRUSTED_PROXY_CIDRS is required" >&2
+    exit 1
+fi
+
+: > /tmp/trusted-proxy-allow.conf
+for trusted_proxy_cidr in $(printf '%s' "$trusted_proxy_cidrs" | tr ',' ' '); do
+    case "$trusted_proxy_cidr" in
+        *[!0-9A-Fa-f:./]*)
+            echo "Invalid trusted proxy CIDR: $trusted_proxy_cidr" >&2
+            exit 2
+            ;;
+    esac
+    printf 'allow %s;\n' "$trusted_proxy_cidr" >> /tmp/trusted-proxy-allow.conf
+done
+
+if [ ! -s /tmp/trusted-proxy-allow.conf ]; then
+    echo "TRUSTED_PROXY_CIDRS must contain at least one CIDR" >&2
+    exit 2
+fi
+
+cp /etc/image/default.conf.template /tmp/nginx.conf
+
+exec nginx -c /tmp/nginx.conf -g 'daemon off;'

deploy/nginx/templates/default.conf.template

@@ -0,0 +1,91 @@
+worker_processes auto;
+pid /tmp/nginx.pid;
+error_log /dev/stderr notice;
+
+events {
+    worker_connections 256;
+}
+
+http {
+  include /etc/nginx/mime.types;
+  access_log /dev/stdout combined;
+  client_body_temp_path /tmp/client_body;
+  proxy_temp_path /tmp/proxy;
+  fastcgi_temp_path /tmp/fastcgi;
+  uwsgi_temp_path /tmp/uwsgi;
+  scgi_temp_path /tmp/scgi;
+
+  server {
+      listen 8080;
+      server_name _;
+      server_tokens off;
+      root /srv/image;
+      disable_symlinks on;
+
+    allow 127.0.0.1;
+    allow ::1;
+    include /tmp/trusted-proxy-allow.conf;
+    deny all;
+
+    location = /healthz {
+        proxy_pass http://image-hook:8081/healthz;
+        proxy_set_header Host $host;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+    }
+
+    location = /v1/status {
+        proxy_pass http://image-hook:8081/v1/status;
+        proxy_set_header Host $host;
+        add_header Access-Control-Allow-Origin "*" always;
+    }
+
+    location = /v1/inventory {
+        proxy_pass http://image-hook:8081/v1/inventory;
+        proxy_set_header Host $host;
+        proxy_buffering off;
+        add_header Access-Control-Allow-Origin "*" always;
+    }
+
+    location = /v1/hooks/gitea {
+        limit_except POST { deny all; }
+        client_max_body_size 1m;
+        proxy_pass http://image-hook:8081/v1/hooks/gitea;
+        proxy_set_header Host $host;
+        proxy_set_header X-Gitea-Signature $http_x_gitea_signature;
+        proxy_set_header X-Gitea-Event $http_x_gitea_event;
+        proxy_set_header X-Gitea-Delivery $http_x_gitea_delivery;
+        proxy_request_buffering on;
+    }
+
+    location ^~ /v1/admin/ { return 404; }
+    location = /image { return 404; }
+    location = /image/ { return 404; }
+    location ^~ /image/ { rewrite ^/image/(.*)$ /$1 last; }
+
+    location ^~ /game/ {
+        try_files $uri =404;
+        add_header Access-Control-Allow-Origin "*" always;
+        add_header X-Content-Type-Options nosniff always;
+    }
+
+    location ^~ /icons/ {
+        try_files $uri =404;
+        add_header Access-Control-Allow-Origin "*" always;
+        add_header X-Content-Type-Options nosniff always;
+    }
+
+    location = /hook/list.json {
+        try_files $uri =404;
+        add_header Access-Control-Allow-Origin "*" always;
+    }
+
+    location = /hook/inventory.v2.json {
+        try_files $uri =404;
+        add_header Access-Control-Allow-Origin "*" always;
+    }
+
+    location ~ (^|/)\. { return 404; }
+    location ~ \.php$ { return 404; }
+      location / { return 404; }
+  }
+}

deploy/scripts/admin-deploy.sh

@@ -0,0 +1,17 @@
+#!/bin/sh
+set -eu
+
+if [ "$#" -lt 1 ] || [ "$#" -gt 2 ]; then
+    echo "Usage: $0 <branch> [commit]" >&2
+    exit 2
+fi
+
+script_dir=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)
+repository_dir=$(CDPATH= cd -- "$script_dir/../.." && pwd)
+branch=$1
+commit=${2:-}
+set -- deploy --branch "$branch"
+if [ -n "$commit" ]; then
+    set -- "$@" --commit "$commit"
+fi
+exec docker compose --project-directory "$repository_dir" exec -T image-hook node src/admin-cli.mjs "$@"

deploy/scripts/firewall-8191.sh

@@ -0,0 +1,69 @@
+#!/bin/sh
+set -eu
+
+action=${1:-check}
+trusted_proxy_cidrs=${TRUSTED_PROXY_CIDRS:-${CADDY_SOURCE_CIDR:-}}
+image_port=${IMAGE_PORT:-8191}
+chain=SAM_IMAGE_INGRESS
+
+case "$image_port" in
+    ''|*[!0-9]*) echo "IMAGE_PORT must be numeric" >&2; exit 2 ;;
+esac
+
+require_root() {
+    if [ "$(id -u)" -ne 0 ]; then
+        echo "Run this action as root." >&2
+        exit 1
+    fi
+}
+
+case "$action" in
+    check)
+        iptables -S DOCKER-USER 2>/dev/null | grep -F "$chain" || true
+        iptables -S "$chain" 2>/dev/null || true
+        ;;
+    apply)
+        require_root
+        if [ -z "$trusted_proxy_cidrs" ]; then
+            echo "TRUSTED_PROXY_CIDRS is required" >&2
+            exit 2
+        fi
+        rule_count=0
+        for trusted_proxy_cidr in $(printf '%s' "$trusted_proxy_cidrs" | tr ',' ' '); do
+            case "$trusted_proxy_cidr" in
+                *[!0-9A-Fa-f:./]*)
+                    echo "Invalid trusted proxy CIDR: $trusted_proxy_cidr" >&2
+                    exit 2
+                    ;;
+            esac
+            rule_count=$((rule_count + 1))
+        done
+        if [ "$rule_count" -eq 0 ]; then
+            echo "TRUSTED_PROXY_CIDRS must contain at least one CIDR" >&2
+            exit 2
+        fi
+        iptables -n -L DOCKER-USER >/dev/null
+        iptables -n -L "$chain" >/dev/null 2>&1 || iptables -N "$chain"
+        iptables -F "$chain"
+        iptables -A "$chain" -j DROP
+        for trusted_proxy_cidr in $(printf '%s' "$trusted_proxy_cidrs" | tr ',' ' '); do
+            iptables -I "$chain" 1 -s "$trusted_proxy_cidr" -j ACCEPT
+        done
+        iptables -C DOCKER-USER -p tcp -m conntrack --ctorigdstport "$image_port" -j "$chain" 2>/dev/null \
+            || iptables -I DOCKER-USER 1 -p tcp -m conntrack --ctorigdstport "$image_port" -j "$chain"
+        ;;
+    remove)
+        require_root
+        while iptables -C DOCKER-USER -p tcp -m conntrack --ctorigdstport "$image_port" -j "$chain" 2>/dev/null; do
+            iptables -D DOCKER-USER -p tcp -m conntrack --ctorigdstport "$image_port" -j "$chain"
+        done
+        if iptables -n -L "$chain" >/dev/null 2>&1; then
+            iptables -F "$chain"
+            iptables -X "$chain"
+        fi
+        ;;
+    *)
+        echo "Usage: $0 [check|apply|remove]" >&2
+        exit 2
+        ;;
+esac

deploy/scripts/init-secrets.sh

@@ -0,0 +1,21 @@
+#!/bin/sh
+set -eu
+
+script_dir=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)
+repository_dir=$(CDPATH= cd -- "$script_dir/../.." && pwd)
+secret_dir="$repository_dir/secrets"
+state_dir="$repository_dir/runtime-data"
+
+umask 077
+mkdir -p "$secret_dir"
+mkdir -p "$state_dir"
+for name in gitea_webhook_secret image_admin_secret; do
+    path="$secret_dir/$name"
+    if [ ! -e "$path" ]; then
+        openssl rand -hex 32 > "$path"
+    fi
+    chmod 600 "$path"
+done
+chmod 700 "$state_dir"
+
+echo "Secret files are ready in $secret_dir (values not printed)."