@snowcone-app/mockup-resolver 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,10 @@
1
+ # Local-dev overrides for `pnpm dev` (standalone). Copy this to `.dev.vars`.
2
+ #
3
+ # The committed wrangler.jsonc `vars` are now PRODUCTION defaults (snowcone index,
4
+ # api.snowcone.app). These values point local dev at the dev catalog + the local
5
+ # backend instead. process-compose passes the same values as `--var` flags, so
6
+ # you only need `.dev.vars` when running `pnpm dev` outside process-compose.
7
+ URL_SIGNING_SECRET=dev-unsigned
8
+ MEILISEARCH_INDEX=snowcone-dev
9
+ KV_CACHE_BASE_URL=http://localhost:4000
10
+ MOCKUP_BASE_URL=http://localhost:8089
package/.env.example ADDED
@@ -0,0 +1,9 @@
1
+ # Mockup Resolver Service Environment Variables
2
+ # Copy this file to .env for local development
3
+
4
+ # Security
5
+ # --------
6
+ # Secret used for signing URLs. This should be a strong random string.
7
+ # In production, set this using Wrangler secrets: wrangler secret put SIGNING_SECRET
8
+ SIGNING_SECRET=your_secure_random_secret_here
9
+
package/DEPLOY.md ADDED
@@ -0,0 +1,152 @@
1
+ # Deploying `mockup-resolver` (production)
2
+
3
+ The `mockup-resolver` Cloudflare Worker resolves + signs mockup render URLs
4
+ (ADR-0073 §10). This runbook covers what must be provisioned for production so
5
+ the signed-URL and `/mockups/url` (Tier-1 `getMockupUrl`) paths actually work —
6
+ **today only the local `dev-unsigned` bypass works end-to-end**; production needs
7
+ the secrets and account data below.
8
+
9
+ > Binding names below are what the code in `src/index.ts` reads. Some
10
+ > `package.json` helper scripts still say `SIGNING_SECRET` (stale) — the worker
11
+ > reads **`URL_SIGNING_SECRET`**. Prefer the explicit `wrangler secret put`
12
+ > commands here over those scripts.
13
+
14
+ ## Environments
15
+
16
+ | | name | custom domain | compositor (`MOCKUP_BASE_URL`) | backend (`KV_CACHE_BASE_URL`) |
17
+ |---|---|---|---|---|
18
+ | production | `mockup-resolver-production` | `s.snowcone.app` | `https://cdn.snowcone.app` | `https://api.snowcone.app` |
19
+ | development | `mockup-resolver-development` | — | (per env) | `http://localhost:4000` |
20
+
21
+ Non-secret vars live in `wrangler.jsonc`. Secrets are **never** committed —
22
+ set them with `wrangler secret put` (below).
23
+
24
+ ## 1. `URL_SIGNING_SECRET` — the signing key (load-bearing)
25
+
26
+ The signature is `HMAC-SHA256(URL_SIGNING_SECRET, <relative path+query>)`
27
+ truncated to the first 8 bytes, hex-encoded (`src/signing.ts`). It is
28
+ **deterministic** — no timestamp/nonce/expiry — which is exactly what makes a
29
+ signed URL a stable CDN cache key (ADR-0073 §10).
30
+
31
+ This secret is **one half of a two-sided contract**: the rendercenter verifier
32
+ (`services/rendercenter/api/src/utils/url-verifier.ts`) re-computes the same HMAC
33
+ over the relative request URL using *its* `URL_SIGNING_SECRET`
34
+ (`services/rendercenter/api/src/config.ts`, which defaults to `dev-unsigned`).
35
+ **The signer and rendercenter must hold the identical secret value**, or every
36
+ production render returns a signature-invalid error.
37
+
38
+ ```bash
39
+ # Generate once, set on BOTH sides with the SAME value:
40
+ openssl rand -hex 32 # → <SECRET>
41
+
42
+ # Signer (this worker):
43
+ npx wrangler secret put URL_SIGNING_SECRET --env production # paste <SECRET>
44
+
45
+ # Rendercenter (its own deploy): set URL_SIGNING_SECRET=<SECRET> the same way
46
+ # its config consumes secrets. Roll both together.
47
+ ```
48
+
49
+ Rotation = set a new value on both sides in lockstep. There is no per-URL
50
+ revocation; rotating the secret invalidates every previously-signed URL (and
51
+ busts the cache), which is the intended revocation lever.
52
+
53
+ When `URL_SIGNING_SECRET` is unset/`dev-unsigned`, `/mockups/url` takes the
54
+ **local-dev bypass** (skips account auth). In production the real secret is set,
55
+ so that branch is never taken and full API-key + account auth always runs
56
+ (`handleMockupUrl` in `src/index.ts`).
57
+
58
+ ## 2. Account-config fallback: `KV_CACHE_BASE_URL` + `KV_CACHE_SERVICE_TOKEN`
59
+
60
+ When an account isn't found in the `ACCOUNTS` KV namespace, the signer falls
61
+ back to the backend's `GET /kv-cache/api-key` endpoint (ADR-0073 §1). Both the
62
+ URL and the token are now env-configured (no longer hardcoded):
63
+
64
+ - **`KV_CACHE_BASE_URL`** — non-secret var, already set per-env in
65
+ `wrangler.jsonc` (`https://api.snowcone.app` in production). The worker appends
66
+ `/kv-cache/api-key`.
67
+ - **`KV_CACHE_SERVICE_TOKEN`** — **secret**, no source default. It must equal the
68
+ backend's `KV_CACHE_SERVICE_SECRET` Encore secret
69
+ (`apps/backend/user/routes/kvCacheRoute.ts` rejects any other Bearer token).
70
+
71
+ ```bash
72
+ npx wrangler secret put KV_CACHE_SERVICE_TOKEN --env production # = backend KV_CACHE_SERVICE_SECRET
73
+ ```
74
+
75
+ If `KV_CACHE_SERVICE_TOKEN` is unset, the worker skips the fallback and returns
76
+ a clear "configuration source unavailable" auth error rather than calling the
77
+ backend with an empty bearer.
78
+
79
+ > **Security — rotate the old token.** The previous hardcoded dev token
80
+ > (`YTcXDJjbYcmUAhLNXDyZHypDCnLbDvZTLFEwBnq7`) is in git history. Rotate the
81
+ > backend's `KV_CACHE_SERVICE_SECRET` and set the new value as
82
+ > `KV_CACHE_SERVICE_TOKEN` here.
83
+
84
+ > **Local dev:** the token is passed via process-compose `--var` (same channel
85
+ > as `URL_SIGNING_SECRET` / `MOCKUP_BASE_URL`), not via `.dev.vars`. In practice
86
+ > the local `ACCOUNTS` KV is seeded (`pnpm seed:local`) and the `dev-unsigned`
87
+ > bypass skips auth, so the fallback is rarely exercised locally.
88
+
89
+ ## 3. Account / API-key provisioning (so `/mockups/url` auth works in prod)
90
+
91
+ In production, `/sign`, `/verify`, and the authenticated `/mockups/url` path all
92
+ call `authenticate()`, which requires the account to be resolvable **and** a
93
+ valid credential:
94
+
95
+ - The `accountId` (= `shop.id`) must exist either in the `ACCOUNTS` KV namespace
96
+ or be fetchable via the §2 backend fallback.
97
+ - The caller must send `x-api-key` matching a stored key whose SHA-256 `hash`
98
+ matches and whose `scopes` include **`mockups`** (server-side BFF path), **or**
99
+ use the public browser path, which is gated by rate limits plus (when
100
+ configured) the asset-source allowlist and signed URLs — **not** by a
101
+ page-origin/domain allowlist, which was removed as unenforceable (browsers
102
+ strip/spoof `Origin`/`Referer`). See ADR-0075/0076.
103
+
104
+ Seed/refresh account data in the production KV namespace
105
+ (`ACCOUNTS`, id `de3d0db77ca34aeaa95e808e574d2f04`) via `pnpm seed:prod`
106
+ (`scripts/seed-prod-kv.js`) or let the backend fallback populate it on first
107
+ miss. Account record shape:
108
+
109
+ ```jsonc
110
+ {
111
+ "accountId": "<shop.id>",
112
+ "apiKeys": [
113
+ { "prefix": "<first 8 chars>", "hash": "<sha256(full key)>",
114
+ "scopes": ["mockups"], "rateLimit": 60 }
115
+ ],
116
+ "public": { "rateLimit": 100 },
117
+ "assetAllowlist": ["cdn.example.com"],
118
+ "requireSig": false
119
+ }
120
+ ```
121
+
122
+ ## 4. Deploy
123
+
124
+ ```bash
125
+ # From workers/mockup-resolver:
126
+ npx wrangler deploy --dry-run --outdir /tmp/mockup-resolver # sanity: bundles clean
127
+ npx wrangler deploy --env production
128
+ ```
129
+
130
+ Verify after deploy: a BFF call to `https://s.snowcone.app/mockups/url` with a
131
+ valid `x-api-key` returns `{ url }`, and loading that URL from
132
+ `https://cdn.snowcone.app` renders (signature accepted by rendercenter).
133
+
134
+ ## Deferred (documented, not built)
135
+
136
+ - **`api.snowcone.app` path-routing.** Instead of the dedicated `s.snowcone.app`
137
+ custom domain, the signer could be mounted under `api.snowcone.app/v1/mockups/*`
138
+ (the public-API surface in ADR-0073 §2) via a Workers route pattern
139
+ (`api.snowcone.app/v1/mockups/*`) plus the matching path handling in
140
+ `src/index.ts`. Deferred until the unified `api.snowcone.app` gateway exists;
141
+ the current custom-domain deploy stands on its own.
142
+
143
+ - **Canonicalize signer params before HMAC (ADR-0073 §10 / open question #7).**
144
+ Sorting query params before signing would make determinism caller-independent
145
+ instead of relying on the shared `@snowcone-app/mockup-url` builder's fixed
146
+ param order. **Not done here** because it is a lockstep change: the rendercenter
147
+ verifier (`services/rendercenter` submodule) HMACs the params as received, so
148
+ changing the signer's ordering without changing the verifier in the same
149
+ release breaks every signature. Do them together in a dedicated change.
150
+
151
+ - **Fate of the public-origin auth method (open question #6)** — keep, tighten,
152
+ or sunset in favor of BFF + key. No change here; documented for the decision.
package/Icon/r ADDED
File without changes
package/README.md ADDED
@@ -0,0 +1,241 @@
1
+ # Mockup Resolver
2
+
3
+ A Cloudflare Worker that resolves, authenticates, and redirects mockup requests.
4
+ Signing/verifying URLs (HMAC-SHA256) is part of what it does.
5
+
6
+ ## Features
7
+
8
+ - Sign URLs with a truncated HMAC-SHA256 signature
9
+ - Verify URL signatures
10
+ - Secure implementation using Web Crypto API
11
+ - Timing-safe comparison for security against timing attacks
12
+ - Dual authentication methods:
13
+ - API Key authentication
14
+ - Client ID + Origin authentication
15
+ - Local KV storage for development
16
+ - Edge-optimized deployment through Cloudflare Workers
17
+
18
+ ## Development
19
+
20
+ ```bash
21
+ # Install dependencies
22
+ pnpm install
23
+
24
+ # Seed the local KV store with test data
25
+ pnpm run seed:local
26
+
27
+ # Start local development server (default port 8102)
28
+ pnpm run dev:local
29
+
30
+ # Check if the service is running correctly
31
+ pnpm run check
32
+
33
+ # Run tests
34
+ pnpm run test
35
+
36
+ # Deploy to Cloudflare
37
+ pnpm deploy
38
+ ```
39
+
40
+ ## Deployment to Cloudflare Edge Network
41
+
42
+ This service is deployed to Cloudflare Workers using a hybrid approach:
43
+
44
+ 1. Application code lives in `workers/mockup-resolver/`
45
+ 2. Infrastructure code lives in `infra/cloudflare/`
46
+ 3. Build scripts bridge the gap between application and infrastructure
47
+
48
+ ### Deployment Process
49
+
50
+ ```bash
51
+ # Build the worker for deployment to Cloudflare
52
+ pnpm build:worker
53
+
54
+ # Update routes in the API router
55
+ pnpm update:routes
56
+
57
+ # Deploy just the mockup resolver worker to Cloudflare
58
+ pnpm deploy:worker
59
+
60
+ # Deploy the entire edge infrastructure including mockup resolver
61
+ pnpm deploy:worker:prod
62
+ ```
63
+
64
+ ### Automatic Deployment
65
+
66
+ The mockup resolver worker is automatically deployed to Cloudflare when:
67
+
68
+ 1. Changes are pushed to the `main` branch that affect:
69
+ - `workers/mockup-resolver/**`
70
+ - `infra/cloudflare/**`
71
+ 2. The GitHub workflow is manually triggered
72
+
73
+ ### File Structure
74
+
75
+ - `worker.js` - Core worker implementation that gets packaged for Cloudflare
76
+ - `cloudflare-routes.js` - Route definitions for the mockup resolver
77
+ - `scripts/build-worker.js` - Script to build and copy the worker to infrastructure
78
+ - `scripts/update-routes.js` - Script to update routes in the API router
79
+
80
+ ### Accessing the Service
81
+
82
+ After deployment, the mockup resolver service is accessible at:
83
+
84
+ - `/v1/url-signer/sign` - For signing URLs
85
+ - `/v1/url-signer/verify` - For verifying signed URLs
86
+
87
+ ### Mockup Resolver Routes
88
+
89
+ Example usage:
90
+
91
+ ```bash
92
+ # Sign a URL
93
+ curl "https://api.snowcone.app/v1/url-signer/sign?url=https://example.com/resource.jpg"
94
+
95
+ # Verify a signed URL
96
+ curl "https://api.snowcone.app/v1/url-signer/verify?url=https://example.com/resource.jpg?signature=xxx&expires=123456789"
97
+ ```
98
+
99
+ ## Configuration
100
+
101
+ The service is configured using `wrangler.toml`:
102
+
103
+ ```toml
104
+ [dev]
105
+ port = 8102 # Local development port
106
+
107
+ [vars]
108
+ URL_SIGNING_SECRET = "your-secret-key" # Secret for signing URLs
109
+
110
+ [[kv_namespaces]]
111
+ binding = "API_KEYS" # KV namespace for API keys
112
+ id = "local" # Will be replaced in production
113
+
114
+ [[kv_namespaces]]
115
+ binding = "CLIENT_ORIGINS" # KV namespace for client origins
116
+ id = "local" # Will be replaced in production
117
+ ```
118
+
119
+ ## Authentication
120
+
121
+ The mockup resolver supports two authentication methods:
122
+
123
+ ### 1. API Key Authentication
124
+
125
+ Use an API key in the `x-api-key` header:
126
+
127
+ ```bash
128
+ curl -H "x-api-key: your-api-key" \
129
+ "http://localhost:8102/sign?url=https://example.com/image.jpg"
130
+ ```
131
+
132
+ API keys are stored in the `API_KEYS` KV namespace.
133
+
134
+ ### 2. Client ID + Origin Authentication
135
+
136
+ For browser clients, use the `clientId` URL parameter:
137
+
138
+ ```bash
139
+ curl -H "Origin: http://localhost:3000" \
140
+ "http://localhost:8102/sign?url=https://example.com/image.jpg&clientId=your_client_id"
141
+ ```
142
+
143
+ Allowed origins for each client are stored in the `CLIENT_ORIGINS` KV namespace.
144
+
145
+ ## API Endpoints
146
+
147
+ ### Sign a URL
148
+
149
+ ```
150
+ GET /sign?url=https://example.com/path
151
+ ```
152
+
153
+ Headers (one of the following authentication methods is required):
154
+
155
+ - `x-api-key: your-api-key`
156
+ - `Origin: https://your-allowed-origin.com` + URL parameter `clientId=your_client_id`
157
+
158
+ Response:
159
+
160
+ ```json
161
+ {
162
+ "signature": "a1b2c3d4e5f6g7h8"
163
+ }
164
+ ```
165
+
166
+ ### Verify a URL signature
167
+
168
+ ```
169
+ GET /verify?url=https://example.com/path&signature=a1b2c3d4e5f6g7h8
170
+ ```
171
+
172
+ Headers (one of the following authentication methods is required):
173
+
174
+ - `x-api-key: your-api-key`
175
+ - `Origin: https://your-allowed-origin.com` + URL parameter `clientId=your_client_id`
176
+
177
+ Response:
178
+
179
+ ```json
180
+ {
181
+ "valid": true
182
+ }
183
+ ```
184
+
185
+ ## KV Namespaces
186
+
187
+ The mockup resolver uses two KV namespaces:
188
+
189
+ ### API_KEYS
190
+
191
+ Stores API keys with the following format:
192
+
193
+ - Key: `api-key-value` (e.g., "test-api-key-1")
194
+ - Value: Client identifier (e.g., "client_1")
195
+
196
+ ### CLIENT_ORIGINS
197
+
198
+ Stores allowed origins for each client with the following format:
199
+
200
+ - Key: Client identifier (e.g., "client_1")
201
+ - Value: JSON array of allowed origins (e.g., `["https://example.com", "https://app.example.com", "*.example.com"]`)
202
+
203
+ Origins can be specified in two ways:
204
+
205
+ 1. Exact match: e.g., "https://example.com"
206
+ 2. Wildcard pattern: e.g., "\*.example.com" - matches any subdomain of example.com
207
+
208
+ Note: Wildcard patterns only match subdomains. For example, "\*.example.com" will match "sub.example.com" but not "example.com" itself.
209
+
210
+ ## Testing
211
+
212
+ A comprehensive test suite is included in `scripts/test-mockup-resolver.ts`. Run the tests with:
213
+
214
+ ```bash
215
+ pnpm run test
216
+ ```
217
+
218
+ The test suite verifies:
219
+
220
+ - API key authentication
221
+ - Client ID + Origin authentication
222
+ - URL signing and verification
223
+ - Error handling
224
+
225
+ ## Security Notes
226
+
227
+ - Uses Web Crypto API for cryptographic operations
228
+ - Implements timing-safe comparison to prevent timing attacks
229
+ - Truncates signatures to 8 bytes (64 bits) for URL friendliness while maintaining security
230
+ - Validates origins to prevent cross-site request forgery
231
+ - Requires authentication for all operations
232
+
233
+ ## Production Deployment
234
+
235
+ When deploying to production:
236
+
237
+ 1. Create KV namespaces in your Cloudflare account
238
+ 2. Update the `wrangler.toml` file with your KV namespace IDs
239
+ 3. Set a strong `URL_SIGNING_SECRET` environment variable
240
+ 4. Seed your production KV namespaces with real API keys and client origins
241
+ 5. Deploy the worker with `pnpm deploy`
@@ -0,0 +1,27 @@
1
+ {
2
+ "apiKeys": {
3
+ "dev-api-key": {
4
+ "rateLimit": 1000
5
+ },
6
+ "dev-api-key-2": {
7
+ "rateLimit": 1000
8
+ },
9
+ "dev-api-key-readonly": {
10
+ "rateLimit": 500
11
+ },
12
+ "test-api-key-1": {
13
+ "rateLimit": 2000
14
+ },
15
+ "test-api-key-1-readonly": {
16
+ "rateLimit": 500
17
+ }
18
+ },
19
+ "clientIds": {
20
+ "dev_client": {
21
+ "rateLimit": 100
22
+ },
23
+ "client_all_origins": {
24
+ "rateLimit": 50
25
+ }
26
+ }
27
+ }
@@ -0,0 +1,61 @@
1
+ [
2
+ {
3
+ "key": "account123",
4
+ "value": {
5
+ "accountId": "account123",
6
+ "apiKeys": {
7
+ "dev-api-key": {
8
+ "rateLimit": 1000
9
+ },
10
+ "dev-api-key-2": {
11
+ "rateLimit": 1000
12
+ },
13
+ "dev-api-key-readonly": {
14
+ "rateLimit": 500
15
+ },
16
+ "test-api-key-1": {
17
+ "rateLimit": 2000
18
+ },
19
+ "test-api-key-1-readonly": {
20
+ "rateLimit": 500
21
+ }
22
+ },
23
+ "clientIds": {
24
+ "dev_client": {
25
+ "rateLimit": 100
26
+ },
27
+ "client_all_origins": {
28
+ "rateLimit": 50
29
+ }
30
+ }
31
+ }
32
+ },
33
+ {
34
+ "key": "account456",
35
+ "value": {
36
+ "accountId": "account456",
37
+ "apiKeys": {
38
+ "test-api-key-2": {
39
+ "rateLimit": 2000
40
+ },
41
+ "test-api-key-2-readonly": {
42
+ "rateLimit": 500
43
+ },
44
+ "sdk-test-key-1": {
45
+ "rateLimit": 1000
46
+ },
47
+ "sdk-test-key-2": {
48
+ "rateLimit": 1000
49
+ }
50
+ },
51
+ "clientIds": {
52
+ "client_1": {
53
+ "rateLimit": 200
54
+ },
55
+ "client_2": {
56
+ "rateLimit": 300
57
+ }
58
+ }
59
+ }
60
+ }
61
+ ]
@@ -0,0 +1,21 @@
1
+ /**
2
+ * Cloudflare Routes Definition for Mockup Resolver
3
+ *
4
+ * This file defines the routes that the mockup resolver will handle.
5
+ * It's used by the infrastructure deployment to configure the worker.
6
+ * Changes to this file should be synchronized with the worker implementation.
7
+ */
8
+
9
+ module.exports = {
10
+ // Service information
11
+ service: {
12
+ name: 'mockup-resolver',
13
+ type: 'edge',
14
+ workerName: 'mockup-resolver',
15
+ },
16
+
17
+ // Path prefix for all mockup resolver routes
18
+ pathPrefix: '/v1/url-signer',
19
+
20
+ // No need for detailed schemas if you just need routing
21
+ }