gorsee 0.1.0

package/src/types/safe-url.ts

@@ -0,0 +1,40 @@
+declare const __safeURLBrand: unique symbol
+
+export type SafeURLValue = string & { readonly [__safeURLBrand]: true }
+
+const ALLOWED_PROTOCOLS = ["http:", "https:", "mailto:"]
+const DANGEROUS_PROTOCOLS = ["javascript:", "data:", "vbscript:", "blob:"]
+
+export function validateURL(raw: string): SafeURLValue {
+  // Check dangerous protocols before URL parsing (handles case-insensitive)
+  const lower = raw.trim().toLowerCase()
+  for (const proto of DANGEROUS_PROTOCOLS) {
+    if (lower.startsWith(proto)) {
+      throw new Error(`[GORSEE E005] Dangerous URL protocol: "${proto}" is not allowed`)
+    }
+  }
+
+  let url: URL
+  try {
+    url = new URL(raw)
+  } catch {
+    // Relative URLs are allowed (they don't parse as absolute URLs)
+    return raw as SafeURLValue
+  }
+
+  if (!ALLOWED_PROTOCOLS.includes(url.protocol)) {
+    throw new Error(
+      `[GORSEE E005] Disallowed URL protocol: "${url.protocol}". Allowed: ${ALLOWED_PROTOCOLS.join(", ")}`
+    )
+  }
+
+  return raw as SafeURLValue
+}
+
+export function SafeURL(
+  strings: TemplateStringsArray,
+  ...values: unknown[]
+): SafeURLValue {
+  const raw = String.raw(strings, ...values.map(String))
+  return validateURL(raw)
+}

package/src/types/user-input.ts

@@ -0,0 +1,12 @@
+declare const __userInputBrand: unique symbol
+
+export type UserInput<T> = T & { readonly [__userInputBrand]: true }
+
+export interface ValidationSchema<T> {
+  parse(raw: unknown): T
+}
+
+export function validate<T>(schema: ValidationSchema<T>, raw: unknown): UserInput<T> {
+  const parsed = schema.parse(raw)
+  return parsed as UserInput<T>
+}

package/src/unsafe/index.ts

@@ -0,0 +1,18 @@
+import type { SafeSQLValue } from "../types/safe-sql.ts"
+import type { SafeHTMLValue } from "../types/safe-html.ts"
+
+/**
+ * DANGER: Bypasses SQL safety. Only use when you know the string is safe.
+ * This function exists as an explicit escape hatch -- its name signals danger.
+ */
+export function unsafeSQL(raw: string): SafeSQLValue {
+  return { text: raw, params: [] } as unknown as SafeSQLValue
+}
+
+/**
+ * DANGER: Bypasses HTML sanitization. Only use for trusted content.
+ * This function exists as an explicit escape hatch -- its name signals danger.
+ */
+export function unsafeHTML(raw: string): SafeHTMLValue {
+  return raw as unknown as SafeHTMLValue
+}