feat: URL validator

.github/workflows/linting.yml

@@ -0,0 +1,30 @@
+name: Linting
+
+on:
+  push:
+    branches-ignore:
+      - develop
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout 🛎️
+        uses: actions/checkout@v3
+        with:
+          persist-credentials: false
+
+      - name: Install pnpm
+        uses: pnpm/action-setup@v4
+
+      - name: Setup Node LTS ✨
+        uses: actions/setup-node@v3
+        with:
+          cache: pnpm
+          node-version: lts/*
+
+      - name: Installing dependencies 📦️
+        run: pnpm install
+
+      - name: Lint 🛀
+        run: pnpm -r run lint

.github/workflows/release.yml

@@ -0,0 +1,46 @@
+name: release
+
+on:
+  push:
+    tags:
+      - "v*"
+  workflow_dispatch: {}
+
+permissions:
+  id-token: write
+  contents: write
+  packages: write
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
+
+      - name: Install pnpm
+        uses: pnpm/action-setup@v4
+
+      - run: corepack enable
+      - uses: actions/setup-node@v3
+        with:
+          node-version: lts/*
+          cache: pnpm
+          registry-url: "https://npm.pkg.github.com"
+          scope: "@opengovsg"
+
+      - run: npx changelogithub
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Install Dependencies
+        run: pnpm i --frozen-lockfile
+
+      - name: 🔨 Build
+        run: pnpm build
+
+      - name: Publish to NPM
+        run: pnpm publish -r --no-git-checks --tag latest --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/tests.yml

@@ -0,0 +1,51 @@
+name: Tests
+
+on:
+  pull_request:
+    branches: [develop]
+  push:
+    branches: [develop]
+
+jobs:
+  tests:
+    runs-on: ubuntu-latest
+    name: Run tests
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+
+      - name: Install pnpm
+        uses: pnpm/action-setup@v4
+
+      - uses: actions/setup-node@v3
+        with:
+          cache: pnpm
+          node-version-file: ".nvmrc"
+
+      - name: Install dependencies
+        run: pnpm install
+
+      - name: Run tests
+        run: |
+          pnpm -r run test
+
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout source code
+        uses: actions/checkout@v3
+
+      - name: Install pnpm
+        uses: pnpm/action-setup@v4
+
+      - uses: actions/setup-node@v3
+        with:
+          cache: pnpm
+          node-version-file: ".nvmrc"
+
+      - name: Install
+        run: pnpm install
+
+      - name: Compile
+        run: |
+          pnpm -r run build

.gitignore

@@ -0,0 +1,40 @@
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+
+# Dependencies
+node_modules
+.pnp
+.pnp.js
+
+# Local env files
+.env
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+# Testing
+coverage
+
+# Turbo
+.turbo
+
+# Vercel
+.vercel
+
+# Build Outputs
+.next/
+out/
+build
+dist
+
+
+# Debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# Misc
+.DS_Store
+*.pem
+.vscode/
+.eslintcache

.nvmrc

@@ -0,0 +1 @@
+v20.10.0

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Open Government Products
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,7 @@
+# Starter Kitty
+
+Common app components that are safe-by-default.
+
+## Packages
+
+- [`@opengovsg/starter-kitty-validators`](./packages/validators/): Common input validators.

package.json

@@ -0,0 +1,19 @@
+{
+  "name": "starter-kitty",
+  "private": true,
+  "scripts": {
+    "build": "turbo build",
+    "dev": "turbo dev",
+    "lint": "turbo lint",
+    "format": "prettier --write \"**/*.{ts,tsx,md}\""
+  },
+  "devDependencies": {
+    "prettier": "^3.2.5",
+    "turbo": "^2.0.6",
+    "typescript": "^5.4.5"
+  },
+  "packageManager": "[email protected]",
+  "engines": {
+    "node": ">=18"
+  }
+}

packages/validators/.eslintrc

@@ -0,0 +1,24 @@
+{
+  "extends": ["opengovsg"],
+  "ignorePatterns": ["dist/**/*", "vitest.config.ts"],
+  "plugins": ["import", "eslint-plugin-tsdoc"],
+  "rules": {
+    "import/no-unresolved": "error",
+    "tsdoc/syntax": "error"
+  },
+  "parser": "@typescript-eslint/parser",
+  "parserOptions": {
+    "project": "**/tsconfig.json"
+  },
+  "settings": {
+    "import/parsers": {
+      "@typescript-eslint/parser": [".ts", ".tsx"]
+    },
+    "import/resolver": {
+      "typescript": {
+        "alwaysTryTypes": true,
+        "project": "**/tsconfig.json"
+      }
+    }
+  }
+}

packages/validators/.prettierignore

@@ -0,0 +1 @@
+tsconfig.json

packages/validators/.prettierrc

@@ -0,0 +1,6 @@
+{
+  "trailingComma": "all",
+  "tabWidth": 2,
+  "semi": false,
+  "singleQuote": true
+}

packages/validators/README.md

@@ -0,0 +1,60 @@
+# Validators
+
+This package provides a set of validators that provide sensible defaults to prevent common security vulnerabilities.
+
+## Class: `UrlValidator`
+
+Validates URLs against a whitelist of allowed protocols and hostnames, preventing open redirects, XSS, SSRF, and other security vulnerabilities.
+
+### new UrlValidator(options)
+
+`options?`: `<Object>`
+
+- `baseOrigin`: `<string>` - The base origin to use for relative URLs. If no base origin is provided, relative URLs will be considered invalid.
+
+  An origin does not include the path or query parameters. For example, a valid base origin is `https://example.com` or `http://localhost:3000`.
+
+- `whitelist`: `<Object>`
+  - `protocols`: `<string[]>` - A list of allowed protocols. If no protocols are provided, the validator will use the default protocols: `['http', 'https']`.
+
+    **Caution: allowing `javascript` or `data` protocols can lead to XSS vulnerabilities.**
+  - `hostnames`: `<string[]>` - A list of allowed hostnames. If no hostnames are provided, the validator will allow any hostname.
+
+    **It is recommended to provide a list of allowed hostnames to prevent open redirects.**
+
+If no options are provided, the validator will use the default options:
+
+```javascript
+{
+  whitelist: {
+    protocols: ['http', 'https'],
+  },
+}
+```
+
+### UrlValidator.parse(url)
+
+- `url`: `<string>` - The URL to parse.
+- Returns: `<URL>` - The parsed URL object.
+- Throws: `<UrlValidationError>` - If the URL is invalid or unsafe.
+
+### Example
+
+```javascript
+const validator = new UrlValidator({
+  whitelist: {
+    protocols: ['http', 'https', 'mailto'],
+    hosts: ['open.gov.sg'],
+  },
+})
+```
+
+Validating a post-login redirect URL provided in a query parameter:
+
+```javascript
+try {
+  router.push(validator.parse(redirectUrl))
+} catch (error) {
+  router.push('/home')
+}
+```

packages/validators/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@opengovsg/starter-kitty-validators",
+  "version": "1.0.0",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup ./src/index.ts --clean --dts --target es2020",
+    "lint": "eslint \"**/*.{js,jsx,ts,tsx}\" --cache",
+    "test": "vitest"
+  },
+  "dependencies": {
+    "zod": "^3.23.8",
+    "zod-validation-error": "^3.3.0"
+  },
+  "devDependencies": {
+    "@types/node": "^18",
+    "@typescript-eslint/eslint-plugin": "^6.21.0",
+    "@typescript-eslint/parser": "^6.0.0",
+    "@swc/core": "^1.6.13",
+    "eslint": "^8.56.0",
+    "eslint-config-opengovsg": "^3.0.0",
+    "eslint-config-prettier": "^8.6.0",
+    "eslint-import-resolver-typescript": "^3.6.1",
+    "eslint-plugin-import": "^2.29.1",
+    "eslint-plugin-simple-import-sort": "^10.0.0",
+    "eslint-plugin-tsdoc": "^0.3.0",
+    "prettier": "^2.8.4",
+    "tsup": "^8.1.0",
+    "typescript": "^5.4.5",
+    "vitest": "^2.0.2"
+  }
+}