Skip to content

Serve .well-known from an undotted origin path - #111

Merged
stiebitzhofer merged 1 commit into
mainfrom
well-known-origin-path
Sep 13, 2026
Merged

stiebitzhofer merged 1 commit into
mainfrom
well-known-origin-path

Conversation

@stiebitzhofer

@stiebitzhofer stiebitzhofer commented Sep 13, 2026

Copy link
Copy Markdown
Member

Summary

https://material-identity.eu/.well-known/security.txt and .../pgp-security.asc returned 404 after #108 merged and deployed green.

actions/upload-pages-artifact builds its tarball with a hardcoded --exclude=.[^/]*, so site/.well-known/ never entered the artifact. Not an input we can flip — include-hidden-files governs the upload of the tar, not what goes into it. Confirmed against the Pages origin directly, which rules out the Worker:

path (Pages origin) before
/.well-known/security.txt 404
/.well-known/pgp-security.asc 404
/context.jsonld 200
/index.html 200

The Worker was faithfully proxying a file that was never uploaded.

Fix

  • scripts/build.ts emits site/well-known/ (undotted). The tracked source stays at .well-known/ in the repo root — that is the convention, and it is what a repo-root consumer expects.
  • worker/index.ts rewrites /.well-known/<x> onto /well-known/<x>, content types and the 1-day ceiling unchanged.

The public URL is untouched: https://material-identity.eu/.well-known/security.txt is the only address RFC 8615 and RFC 9116 care about. The Pages origin is never advertised (deploy.yml says as much), so its internal layout is ours to choose, and mapping a URI onto an origin file is exactly this Worker's job.

Rejected: replacing upload-pages-artifact with a hand-rolled tar + upload-artifact. Tidier origin layout, but it moves the deploy path's correctness into our hands for the sake of a directory name nobody sees.

Two guards

The build test we already had asserted the output path — and passed, green, while production 404'd. Asserting the same fact more loudly would not have helped, so both guards move outward:

  • Build test: nothing under site/ may start with a dot. Catches the whole class, not these two files.
  • Post-deploy smoke in deploy.yml: curls the canonical URLs and fails the run on a non-200, so a silently truncated artifact can no longer look like a successful deploy. Uses curl -f with retries, because the Worker caches its own 404 for 60s and the first probe after a deploy can legitimately still miss.

Closes #110

Test plan

  • npm test — 80/80
  • npm run validate — OK
  • npm run build — emits site/well-known/, no dot-entries anywhere in the tree
  • Worker tests: both content types, the 1-day ceiling, no immutable, nested .well-known paths rewritten, and an assertion that no origin path we produce contains /.
  • deploy.yml parses
  • After merge: the new smoke step is itself the verification — it must pass on the deploy run

Both /.well-known/ URLs 404'd in production after #108 merged and deployed
green. actions/upload-pages-artifact builds its tarball with a hardcoded
`--exclude=.[^/]*`, so site/.well-known/ never entered the artifact. Confirmed
against the Pages origin directly: /context.jsonld 200, /.well-known/* 404 —
the Worker was faithfully proxying a file that was never uploaded.

The build now emits site/well-known/ and the Worker rewrites /.well-known/<x>
onto it. The canonical, RFC-mandated URL is unchanged, which is the only address
RFC 8615 and RFC 9116 care about; the Pages origin is never advertised, so its
internal layout is ours to choose. Rewriting a URI onto an origin file is what
this Worker is for, so this costs no new machinery — the alternative, replacing
upload-pages-artifact with a hand-rolled tar, would put the deploy path's
correctness in our hands to save a directory name nobody sees.

Two guards, because the existing build test asserted the output path and passed
while the site was 404ing:

- a build test asserting nothing under site/ starts with a dot, which catches
  the whole class rather than these two files
- a post-deploy smoke step curling the canonical URLs, so a silently truncated
  artifact fails the run instead of looking like a successful deploy. It uses
  curl -f with retries: the Worker caches its own 404 for 60s, so the first
  probe after a deploy can legitimately still miss.

Closes #110
@stiebitzhofer
stiebitzhofer merged commit bf1e259 into main Sep 13, 2026
2 checks passed
@stiebitzhofer
stiebitzhofer deleted the well-known-origin-path branch September 13, 2026 22:36
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

/.well-known/ 404s in production: upload-pages-artifact strips dot-directories

1 participant