Skip to content

feat: remote link submission at /add, with optional custom slug - #85

Draft
felleg wants to merge 2 commits into
vanityURLs:mainfrom
felleg:work/remote-link-submission
Draft

felleg wants to merge 2 commits into
vanityURLs:mainfrom
felleg:work/remote-link-submission

Conversation

@felleg

@felleg felleg commented Oct 11, 2026

Copy link
Copy Markdown
Collaborator

Note from the contributor: this feature was built and iterated on with an AI coding assistant (Claude Code) while setting up my own instance (f-l.ca). I reviewed and tested the behavior end-to-end on that live instance before porting it here, but I'd appreciate extra scrutiny on the design details below, particularly the Cloudflare Access / CSP interaction, since I can't personally vouch for every implementation detail.

Summary

Adds a browser-based way to add short links to a GitLab-hosted instance without a local checkout. Submitting a URL at /add:

  • picks a collision-free random slug (reusing the same alphabet/length logic as v8s-lnk, extracted into scripts/workers/lib/slug.mjs so both share it) — or accepts a self-chosen one, validated with the same segment rules as v8s-lnk's own custom slugs, checked against reserved routes and existing links;
  • triggers a GitLab pipeline that runs the real v8s-lnk CLI, so all existing validation (check:links), commit, and push logic is reused rather than duplicated.

It's opt-in (links.remote_submission.enabled in site config, off by default) and GitLab-specific for now (triggers a GitLab CI pipeline via the Pipeline Trigger API). A GitHub Actions equivalent seems like a reasonable follow-up but felt like a separate, bigger scope — happy to discuss if there's interest.

Access model

The page is meant to sit behind a dedicated Cloudflare Access Application, since it grants write access to the repository. It uses the general Access audience by default, or a separate CF_ACCESS_SUBMIT_AUD when configured, so a general-site identity doesn't automatically also get write access to /add.

A CSP/CORS detail worth a careful look

Custom HTML pages (anything an instance places under custom/public/) get a CSP sandbox directive without allow-same-origin, which gives them an opaque browser origin. If an instance themes /add into a custom page, its own fetch("/add/submit") would then be treated as cross-origin by the browser, triggering a CORS preflight — and Cloudflare Access always rejects that preflight (OPTIONS requests never carry cookies, by spec), breaking submission entirely before the real POST ever has a chance.

This PR exempts specifically the /add page's asset path from that sandbox (isAddPageAssetPath in worker.mjs) so its fetch keeps running same-origin, carrying the Access session cookie normally. Every other custom page keeps the sandbox. I confirmed this exact failure mode and fix on a live instance (browser console showed CORS Missing Allow Origin on the preflight; wrangler tail never showed the POST reaching the Worker at all until the fix).

I'm flagging this prominently because I'm not 100% certain this is the most idiomatic fix for this codebase — an alternative would be extending the existing Origin: null CORS handling (isPublicCorsEndpoint/withPublicCorsHeaders, already used for /lookup and /expand) to also cover add/submit's preflight, but the actual POST would still need Access's session cookie to travel cross-site, which depends on that cookie's SameSite attribute (not something this PR controls). The sandbox-exemption approach sidesteps that uncertainty entirely, which is why I went with it, but I'd welcome a second opinion.

i18n

Labels are only translated for en/fr so far (noted in a comment in v8s-submit.js); es/it/de fall back to English, unlike v8s-lookup.js's full en/fr/es/it/de set. Happy to add the remaining translations if that's a blocker, but didn't want to guess at translation quality without review.

Testing

  • npm run test:worker — all passing, including new coverage for: Access gating (dedicated vs. general audience), the CSP-sandbox exemption, random slug generation/collision handling, custom slug validation/reservation/collision, and GitLab pipeline trigger wiring.
  • npm run test:slug, npm run lint, npm run format:check — all passing.
  • npm run test:detach fails in my sandbox for an unrelated, pre-existing local git-config reason (git tag v9.9.9 / "fatal: no tag message?"), reproducible on a clean checkout of main with no changes from this PR — not something this PR introduced.

Docs

I didn't add anything to the external docs site (vanityurls.link) since I don't have access to it — happy to write a page for it if that's useful, just let me know the format/location. For now there's a short pointer in README.md and a fairly detailed setup comment block in defaults/gitlab/.gitlab-ci.yml.

Adds a browser-based way to add short links to a GitLab-hosted
instance without a local checkout. Submitting a URL at /add picks a
collision-free random slug (reusing the same alphabet/length logic
as v8s-lnk, extracted into scripts/workers/lib/slug.mjs so both
share it) — or uses a self-chosen one, validated with the same
segment rules as v8s-lnk's own custom slugs, checked against
reserved routes and existing links — and triggers a GitLab pipeline
that runs the real v8s-lnk CLI, reusing all existing validation
(check:links), commit, and push logic rather than duplicating it.

The page is gated behind a dedicated Cloudflare Access Application,
since it grants write access to the repository; it uses the same
audience as the general one by default, or a separate
CF_ACCESS_SUBMIT_AUD when configured, so a general-site identity
doesn't automatically also get write access.

The submit page intentionally does NOT get the CSP `sandbox`
directive that custom HTML assets otherwise receive: its own
fetch("/add/submit") needs to run same-origin so the browser sends
the Access session cookie with it. An opaque (sandboxed) origin
would make that same-host fetch cross-origin, and Access's CORS
preflight always rejects (preflight requests never carry cookies),
breaking submission entirely — see isAddPageAssetPath in worker.mjs.

The feature is opt-in via links.remote_submission in site config
(off by default) and GitLab-specific for now — it triggers a GitLab
CI pipeline via the Pipeline Trigger API. A GitHub Actions
equivalent is a reasonable follow-up but out of scope here.

Labels are only translated for en/fr so far (see the comment in
v8s-submit.js); es/it/de fall back to English, unlike the full
en/fr/es/it/de set v8s-lookup.js already has. Translation
contributions welcome.

Built and tested on a live instance (f-l.ca) before porting here.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
@felleg
felleg requested a review from bhdicaire as a code owner October 11, 2026 22:21
@felleg
felleg marked this pull request as draft October 11, 2026 22:23
@felleg

felleg commented Oct 11, 2026

Copy link
Copy Markdown
Collaborator Author

Marking as draft in case anyone wants to take ownership of this PR. I created this not with the intent of merging as is, but more as a proof of concept.

The job's rules: only skip the job itself on an ordinary push, not
pipeline creation — so the commit it pushes (adding the new link)
was spawning a second, job-less pipeline every time, pure noise with
nothing to run. Add a workflow: rule so a pipeline is only created at
all when triggered via the API (SUBMIT_URL/SUBMIT_SLUG set), matching
this file's one and only job.

Found and fixed after a real instance (f-l.ca) showed this in its
pipeline history.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
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.

1 participant