@gkd-kit/workers

Hono-based Cloudflare Worker for GKD snapshot detection, build asset lookup, and safe public GitHub attachment proxying.

Runtime API

• GET /snapshot-detect/getSnapshotList returns all stored snapshot/import mappings.
• GET /snapshot-detect/getImportId?id=<positive-safe-integer> returns the stored GitHub import ID or null.
• GET /snapshot-detect/detectSnapshot?id=123&importId=456 preserves the original query-string API.
• POST /snapshot-detect/detectSnapshot accepts JSON { "id": 123, "importId": 456 } as the write-oriented alternative. Both forms verify snapshot.json from the public GitHub attachment before storing the mapping in D1.
• GET /build-asset/getBuildAsset?buildKey=<string> returns { "assetId": 123 } or null.
• GET /build-asset/getBuildAssetList returns every stored { "buildKey": "...", "assetId": 123 } mapping ordered by buildKey.
• POST /build-asset/createBuildAsset accepts JSON, URL-encoded form data, or multipart form data containing buildKey and assetId. It requires Authorization: Bearer <token>, creates or updates the D1 mapping, and returns both fields.
• GET /proxy?url=<encoded-github-attachment-url> streams a rate-limited, header-filtered public GitHub ZIP attachment. It accepts current https://github.com/user-attachments/files/<id>/<filename>.zip links and legacy https://github.com/gkd-kit/inspect/files/<id>/<filename>.zip links.
• Framework-generated HEAD and OPTIONS responses do not carry business logic. Unsupported paths, methods, and business errors return HTTP 200 JSON containing error: true; successful JSON APIs return their business data without a response envelope.

The proxy does not forward cookies, authorization headers, or other private request state. Initial targets must match one of the GitHub ZIP attachment formats above without a query string or fragment. Redirects are followed manually and may only remain on an allowed attachment URL or continue to GitHub's objects.githubusercontent.com repository-file storage path. Direct CDN URLs, GitHub Raw or Release URLs, image attachment URLs, non-GitHub hosts, credentials, IP literals, local hostnames, non-default ports, and non-HTTPS URLs are rejected. Successful proxy responses are transparent transport responses and retain the upstream status, selected headers, and body. Proxy errors generated by this Worker use the JSON error contract above.

Authentication

Configure the shared GKD_API_AUTH_TOKEN as a plaintext variable in the Worker's Cloudflare dashboard settings. Wrangler is configured with keep_vars so deployments preserve dashboard-managed variables. For local development, set the same variable in the ignored .dev.vars file:

GKD_API_AUTH_TOKEN=local-development-token

Send the configured value to authenticated routes as a Bearer token. Missing, malformed, or incorrect credentials are rejected before the request body is parsed or D1 is modified.

Development

Requirements are pinned through package.json devEngines. All dependency versions live in the strict pnpm catalog, and pnpm rejects releases newer than one day.

1. Run pnpm install.
2. Run pnpm types after changing wrangler.jsonc to refresh editor types; validation commands regenerate them automatically.
3. Run pnpm d1:migrate:local.
4. Run pnpm dev.

Use pnpm check for type generation, TypeScript checks, Workers/D1 integration tests, and a Wrangler deployment dry-run. Run pnpm audit --audit-level high --registry=https://registry.npmjs.org/ before deployment.

Remote deployment

The configuration binds directly to the existing gkd D1 database by its database ID. Before deploying the build asset routes, apply the checked-in migrations with pnpm d1:migrate:remote. The existing snapshot migration uses CREATE TABLE IF NOT EXISTS, so applying it records the baseline without replacing snapshot data; the next migration adds build_asset.

Deploy to the generated workers.dev hostname before changing any custom-domain routing or removing the old Workers.

Pushes to main and manual GitHub Actions runs targeting main run pnpm check, then use the project-local Wrangler to apply pending D1 migrations and deploy the Worker. Configure repository secrets CLOUDFLARE_API_TOKEN with Workers Scripts Edit and D1 Edit permissions and CLOUDFLARE_ACCOUNT_ID for the target Cloudflare account.

The workflow reads Node and pnpm versions from package.json: actions/setup-node@v6 uses devEngines.runtime, while pnpm/action-setup@v6 uses devEngines.packageManager.

The old snapshot-detect Worker remains the rollback target and is not modified by this package.