kennel 0.1.8

package/package.json

@@ -0,0 +1,74 @@
+{
+  "name": "kennel",
+  "version": "0.1.8",
+  "description": "Schema-backed folder ledger validator for structured workspaces.",
+  "type": "module",
+  "license": "MIT",
+  "bin": {
+    "kennel": "bin/kennel.mjs"
+  },
+  "exports": {
+    "./mcp": {
+      "types": "./dist/package/mcp.d.ts",
+      "import": "./dist/package/mcp.js"
+    },
+    "./mcp/data": {
+      "types": "./dist/package/mcp-data.d.ts",
+      "import": "./dist/package/mcp-data.js"
+    },
+    "./mcp/http": {
+      "types": "./dist/package/mcp-http.d.ts",
+      "import": "./dist/package/mcp-http.js"
+    },
+    "./mcp/notifications/email-worker": {
+      "types": "./dist/package/mcp-email-worker.d.ts",
+      "import": "./dist/package/mcp-email-worker.js"
+    },
+    "./mcp/stdio": {
+      "types": "./dist/package/mcp-stdio.d.ts",
+      "import": "./dist/package/mcp-stdio.js"
+    },
+    "./automations/notifications": {
+      "types": "./dist/automations/notifications.d.ts",
+      "import": "./dist/automations/notifications.js"
+    }
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "files": [
+    "bin",
+    "dist",
+    "templates"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "npm run build && node --test tests/*.test.mjs",
+    "check": "npm run build && node --check bin/kennel.mjs && node --check dist/main.js",
+    "prepack": "npm run build",
+    "pack:check": "npm pack --dry-run",
+    "publish:public": "npm publish --access public --registry=https://registry.npmjs.org --@raggle-ai:registry=https://registry.npmjs.org",
+    "publish:public:dry-run": "npm publish --dry-run --access public --registry=https://registry.npmjs.org --@raggle-ai:registry=https://registry.npmjs.org"
+  },
+  "dependencies": {
+    "@raggle-ai/kennel-mcp": "^0.1.7",
+    "ajv": "^8.17.1",
+    "ajv-formats": "^3.0.1",
+    "effect": "^3.11.9",
+    "yaml": "^2.9.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.13.4",
+    "typescript": "^5.9.3"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/raggle-ai/kennel.git",
+    "directory": "cli"
+  }
+}

package/templates/cloudflare/email-code-worker.js

@@ -0,0 +1,344 @@
+const AUTH_PREFIX = '/__kennel_auth'
+const SESSION_COOKIE = '__kennel_auth_session'
+const CHALLENGE_COOKIE = '__kennel_auth_challenge'
+const SESSION_MAX_AGE = 60 * 60 * 24 * 7
+const CHALLENGE_MAX_AGE = 60 * 10
+
+const encoder = new TextEncoder()
+
+export default {
+  async fetch(request, env) {
+    const url = new URL(request.url)
+
+    if (isAdminMcpRequest(url, env)) return proxyAdminMcpRequest(request, env)
+
+    if (url.pathname === `${AUTH_PREFIX}/request` && request.method === 'POST') return requestCode(request, env)
+    if (url.pathname === `${AUTH_PREFIX}/verify` && request.method === 'POST') return verifyCode(request, env)
+    if (url.pathname === `${AUTH_PREFIX}/logout`) return logout(url)
+
+    if (isPublicAsset(url.pathname, env)) return assetResponse(request, env)
+    if (request.headers.has('Cf-Access-Jwt-Assertion')) return assetResponse(request, env)
+    if (await hasSession(request, env)) return assetResponse(request, env)
+
+    return loginPage(url)
+  },
+}
+
+function isAdminMcpRequest(url, env) {
+  if (!env.KENNEL_ADMIN_MCP_UPSTREAM) return false
+  if (!url.pathname.startsWith('/mcp')) return false
+  const hostnames = csv(env.KENNEL_ADMIN_MCP_HOSTNAMES)
+  return hostnames.length === 0 || hostnames.includes(url.hostname.toLowerCase())
+}
+
+async function proxyAdminMcpRequest(request, env) {
+  if (!env.KENNEL_MCP_ACCESS_HEADER_TOKEN) return json({ error: 'Missing KENNEL_MCP_ACCESS_HEADER_TOKEN.' }, 500)
+
+  const incomingUrl = new URL(request.url)
+  const upstream = new URL(env.KENNEL_ADMIN_MCP_UPSTREAM)
+  upstream.search = incomingUrl.search
+
+  const headers = new Headers(request.headers)
+  headers.delete('host')
+  headers.set('x-kennel-access-token', env.KENNEL_MCP_ACCESS_HEADER_TOKEN)
+  headers.set('x-kennel-mcp-role', env.KENNEL_ADMIN_MCP_ROLE || 'admin')
+  const email = request.headers.get('cf-access-authenticated-user-email')
+  if (email) headers.set('cf-access-authenticated-user-email', email)
+
+  return fetch(new Request(upstream, {
+    body: request.body,
+    headers,
+    method: request.method,
+    redirect: 'manual',
+  }))
+}
+
+async function assetResponse(request, env) {
+  const response = await env.ASSETS.fetch(request)
+  if (response.status !== 404) return response
+
+  const url = new URL(request.url)
+  const base = siteBase(env)
+  if (!base || !url.pathname.startsWith(base)) return response
+
+  const stripped = new URL(request.url)
+  stripped.pathname = `/${url.pathname.slice(base.length)}`.replace(/\/+/g, '/')
+  return env.ASSETS.fetch(new Request(stripped, request))
+}
+
+function isPublicAsset(pathname, env) {
+  const normalized = stripSiteBase(pathname, env)
+  return normalized.startsWith('/assets/') || normalized === '/favicon.ico' || normalized === '/robots.txt' || normalized === '/vp-icons.css'
+}
+
+function stripSiteBase(pathname, env) {
+  const base = siteBase(env)
+  if (!base || !pathname.startsWith(base)) return pathname
+  return `/${pathname.slice(base.length)}`.replace(/\/+/g, '/')
+}
+
+function siteBase(env) {
+  const base = String(env.KENNEL_SITE_BASE ?? '').trim()
+  if (!base || base === '/') return ''
+  return `/${base.replace(/^\/+|\/+$/g, '')}/`
+}
+
+async function requestCode(request, env) {
+  const url = new URL(request.url)
+  const form = await request.formData()
+  const email = String(form.get('email') ?? '').trim().toLowerCase()
+  const redirect = cleanRedirect(form.get('redirect'))
+
+  if (!email || !isAllowedEmail(email, env)) return loginPage(url, 'Use an approved email address.', email, redirect)
+
+  const code = String(crypto.getRandomValues(new Uint32Array(1))[0] % 1000000).padStart(6, '0')
+  const expires = Math.floor(Date.now() / 1000) + CHALLENGE_MAX_AGE
+  const challenge = await signPayload({
+    email,
+    codeHash: await codeDigest(email, code, expires, env),
+    expires,
+  }, env)
+
+  await sendCode(email, code, env)
+
+  return htmlResponse(verifyPage(email, redirect), {
+    'Set-Cookie': cookie(CHALLENGE_COOKIE, challenge, CHALLENGE_MAX_AGE, url),
+  })
+}
+
+async function verifyCode(request, env) {
+  const url = new URL(request.url)
+  const form = await request.formData()
+  const code = String(form.get('code') ?? '').replace(/\D/g, '')
+  const redirect = cleanRedirect(form.get('redirect'))
+  const challenge = await readSignedCookie(request, CHALLENGE_COOKIE, env)
+
+  if (!challenge?.email || !challenge.codeHash) return loginPage(url, 'That code expired. Request a new one.', '', redirect)
+  if (challenge.expires < Math.floor(Date.now() / 1000)) return loginPage(url, 'That code expired. Request a new one.', challenge.email, redirect)
+  if ((await codeDigest(challenge.email, code, challenge.expires, env)) !== challenge.codeHash) return htmlResponse(verifyPage(challenge.email, redirect, 'That code did not match.'))
+
+  const session = await signPayload({
+    email: challenge.email,
+    expires: Math.floor(Date.now() / 1000) + SESSION_MAX_AGE,
+  }, env)
+
+  return redirectResponse(redirect, {
+    'Set-Cookie': [cookie(SESSION_COOKIE, session, SESSION_MAX_AGE, url), cookie(CHALLENGE_COOKIE, '', 0, url)],
+  })
+}
+
+function logout(url) {
+  return redirectResponse('/', {
+    'Set-Cookie': [cookie(SESSION_COOKIE, '', 0, url), cookie(CHALLENGE_COOKIE, '', 0, url)],
+  })
+}
+
+async function hasSession(request, env) {
+  const session = await readSignedCookie(request, SESSION_COOKIE, env)
+  if (!session?.email || !session.expires) return false
+  if (session.expires < Math.floor(Date.now() / 1000)) return false
+  return isAllowedEmail(session.email, env)
+}
+
+function isAllowedEmail(email, env) {
+  const allowedEmails = csv(env.KENNEL_AUTH_ALLOWED_EMAILS)
+  const allowedDomains = csv(env.KENNEL_AUTH_ALLOWED_DOMAINS)
+  const domain = email.split('@').pop()
+
+  return allowedEmails.includes(email) || allowedDomains.includes(domain)
+}
+
+async function sendCode(email, code, env) {
+  if (!env.EMAIL?.send) throw new Error('Missing Cloudflare Email binding named EMAIL.')
+  if (!env.KENNEL_AUTH_FROM_EMAIL) throw new Error('Missing KENNEL_AUTH_FROM_EMAIL.')
+
+  await env.EMAIL.send({
+    to: email,
+    from: env.KENNEL_AUTH_FROM_EMAIL,
+    subject: env.KENNEL_AUTH_EMAIL_SUBJECT ?? 'Your sign-in code',
+    text: `Your sign-in code is ${code}.\n\nIt expires in 10 minutes.`,
+  })
+}
+
+async function signPayload(payload, env) {
+  const body = base64Url(JSON.stringify(payload))
+  const signature = await hmac(body, env)
+  return `${body}.${signature}`
+}
+
+async function readSignedCookie(request, name, env) {
+  const value = parseCookies(request.headers.get('Cookie')).get(name)
+  if (!value) return undefined
+
+  const [body, signature] = value.split('.')
+  if (!body || !signature) return undefined
+  if ((await hmac(body, env)) !== signature) return undefined
+
+  try {
+    return JSON.parse(fromBase64Url(body))
+  } catch {
+    return undefined
+  }
+}
+
+async function hmac(value, env) {
+  if (!env.KENNEL_AUTH_SECRET) throw new Error('Missing KENNEL_AUTH_SECRET.')
+
+  const key = await crypto.subtle.importKey('raw', encoder.encode(env.KENNEL_AUTH_SECRET), { name: 'HMAC', hash: 'SHA-256' }, false, ['sign'])
+  const signature = await crypto.subtle.sign('HMAC', key, encoder.encode(value))
+  return base64Url(signature)
+}
+
+async function codeDigest(email, code, expires, env) {
+  return hmac(`${email}:${code}:${expires}`, env)
+}
+
+function loginPage(url, error = '', email = '', redirect = url.pathname + url.search) {
+  return htmlResponse(`<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Sign in</title>
+  ${styles()}
+</head>
+<body>
+  <main>
+    <p class="eyebrow">Protected docs</p>
+    <h1>Sign in with email</h1>
+    <p>Enter an approved email address and we will send you a short access code.</p>
+    ${error ? `<p class="error">${escapeHtml(error)}</p>` : ''}
+    <form method="post" action="${AUTH_PREFIX}/request">
+      <input type="hidden" name="redirect" value="${escapeHtml(redirect)}">
+      <label>Email</label>
+      <input name="email" type="email" autocomplete="email" required value="${escapeHtml(email)}" autofocus>
+      <button type="submit">Send code</button>
+    </form>
+  </main>
+</body>
+</html>`)
+}
+
+function verifyPage(email, redirect, error = '') {
+  return `<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Enter code</title>
+  ${styles()}
+</head>
+<body>
+  <main>
+    <p class="eyebrow">Protected docs</p>
+    <h1>Check your email</h1>
+    <p>We sent a six-digit code to <strong>${escapeHtml(email)}</strong>.</p>
+    ${error ? `<p class="error">${escapeHtml(error)}</p>` : ''}
+    <form method="post" action="${AUTH_PREFIX}/verify">
+      <input type="hidden" name="redirect" value="${escapeHtml(redirect)}">
+      <label>Code</label>
+      <input name="code" inputmode="numeric" pattern="[0-9]*" autocomplete="one-time-code" required autofocus>
+      <button type="submit">Continue</button>
+    </form>
+  </main>
+</body>
+</html>`
+}
+
+function styles() {
+  return `<style>
+    :root { color-scheme: light; font-family: Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; }
+    body { min-height: 100vh; margin: 0; display: grid; place-items: center; background: #f7f8f9; color: #172026; }
+    main { width: min(100% - 32px, 420px); background: #fff; border: 1px solid #d9dee3; border-radius: 8px; padding: 28px; box-shadow: 0 18px 42px rgb(23 32 38 / 9%); }
+    .eyebrow { margin: 0 0 10px; color: #66727f; font-size: 13px; font-weight: 700; text-transform: uppercase; letter-spacing: .08em; }
+    h1 { margin: 0 0 10px; font-size: 26px; line-height: 1.2; letter-spacing: 0; }
+    p { margin: 0 0 18px; color: #4b5965; line-height: 1.55; }
+    label { display: block; margin: 0 0 8px; font-size: 14px; font-weight: 700; }
+    input { box-sizing: border-box; width: 100%; min-height: 44px; border: 1px solid #b8c1ca; border-radius: 6px; padding: 10px 12px; font: inherit; }
+    button { width: 100%; min-height: 44px; margin-top: 14px; border: 0; border-radius: 6px; background: #163b56; color: #fff; font: inherit; font-weight: 700; cursor: pointer; }
+    .error { padding: 10px 12px; border: 1px solid #e1a4a4; border-radius: 6px; background: #fff4f4; color: #8f1f1f; }
+  </style>`
+}
+
+function redirectResponse(location, headers = {}) {
+  return new Response(null, { status: 303, headers: buildHeaders({ Location: location, ...headers }) })
+}
+
+function htmlResponse(body, headers = {}) {
+  return new Response(body, {
+    headers: buildHeaders({
+      'Content-Type': 'text/html; charset=utf-8',
+      'Cache-Control': 'no-store',
+      ...headers,
+    }),
+  })
+}
+
+function json(body, status = 200) {
+  return new Response(JSON.stringify(body), {
+    headers: { 'Content-Type': 'application/json; charset=utf-8' },
+    status,
+  })
+}
+
+function buildHeaders(input) {
+  const headers = new Headers()
+  for (const [name, value] of Object.entries(input)) {
+    if (Array.isArray(value)) {
+      for (const entry of value) headers.append(name, entry)
+      continue
+    }
+    headers.set(name, value)
+  }
+  return headers
+}
+
+function cookie(name, value, maxAge, url) {
+  const secure = url.protocol === 'https:' ? '; Secure' : ''
+  return `${name}=${value}; Path=/; HttpOnly; SameSite=Lax; Max-Age=${maxAge}${secure}`
+}
+
+function parseCookies(header) {
+  const cookies = new Map()
+  for (const part of String(header ?? '').split(';')) {
+    const [name, ...value] = part.trim().split('=')
+    if (name) cookies.set(name, value.join('='))
+  }
+  return cookies
+}
+
+function cleanRedirect(value) {
+  const redirect = String(value ?? '/')
+  if (!redirect.startsWith('/') || redirect.startsWith('//') || redirect.startsWith(AUTH_PREFIX)) return '/'
+  return redirect
+}
+
+function csv(value) {
+  return String(value ?? '')
+    .split(',')
+    .map((item) => item.trim().toLowerCase())
+    .filter(Boolean)
+}
+
+function base64Url(value) {
+  const bytes = typeof value === 'string' ? encoder.encode(value) : new Uint8Array(value)
+  let binary = ''
+  for (const byte of bytes) binary += String.fromCharCode(byte)
+  return btoa(binary).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/g, '')
+}
+
+function fromBase64Url(value) {
+  const padded = value.replace(/-/g, '+').replace(/_/g, '/').padEnd(Math.ceil(value.length / 4) * 4, '=')
+  const binary = atob(padded)
+  const bytes = new Uint8Array(binary.length)
+  for (let index = 0; index < binary.length; index += 1) bytes[index] = binary.charCodeAt(index)
+  return new TextDecoder().decode(bytes)
+}
+
+function escapeHtml(value) {
+  return String(value)
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+}