feat(api, web): implement short install link functionality for agents

- Added new API endpoints for creating, retrieving, and revoking install links for agents.
- Enhanced the agent installation process with short links accessible via `/agent-install/:id` and `/:slug`.
- Updated the README and documentation to reflect the new installation method and usage instructions.
- Refactored relevant components in the web application to support the new install link feature.
- Improved error handling and validation for install link operations.

Co-authored-by: Cursor <[email protected]>

apps/api/src/services/install-links.test.ts

@@ -0,0 +1,62 @@
+import { describe, it, expect, afterAll } from 'vitest'
+import { buildApp } from '../app.js'
+import type { AppConfig } from '../config.js'
+
+const testConfig: AppConfig = {
+  databaseUrl: 'sqlite::memory:',
+  jwtSecret: 'test',
+  jwtTtlHours: 24,
+  serverPort: 8080,
+  staticDir: null,
+  logLevel: 'error',
+  authRequired: false,
+  authIssuer: 'https://auth.test',
+  authPortalUrl: 'http://localhost:5175',
+  publicBaseUrl: 'https://fw.example.com',
+  enrollSeed: 'test-seed',
+}
+
+describe('install-links', () => {
+  const appPromise = buildApp({ memory: true, config: testConfig })
+
+  afterAll(async () => {
+    const app = await appPromise
+    await app.close()
+  })
+
+  it('creates link and serves scripts by id and slug', async () => {
+    const app = await appPromise
+    await app.ready()
+
+    const created = await app.inject({
+      method: 'POST',
+      url: '/api/v1/install-links',
+      payload: { name: 'web-01', platform: 'linux' },
+    })
+    expect(created.statusCode).toBe(201)
+    const body = created.json() as {
+      id: string
+      slug: string
+      curl: { by_id: string; by_slug: string }
+    }
+    expect(body.id).toBeTruthy()
+    expect(body.slug).toBeTruthy()
+    expect(body.curl.by_id).toContain(`/agent-install/${body.id}`)
+
+    const byId = await app.inject({
+      method: 'GET',
+      url: `/agent-install/${body.id}`,
+    })
+    expect(byId.statusCode).toBe(200)
+    expect(byId.headers['content-type']).toContain('text/x-shellscript')
+    expect(byId.body).toContain("EVOFW_CLIENT_NAME='web-01'")
+    expect(byId.body).toContain("EVOFW_SEED='test-seed'")
+
+    const bySlug = await app.inject({
+      method: 'GET',
+      url: `/${body.slug}`,
+    })
+    expect(bySlug.statusCode).toBe(200)
+    expect(bySlug.body).toContain("EVOFW_CP_URL='https://fw.example.com'")
+  })
+})

apps/api/src/services/install-links.ts

@@ -0,0 +1,127 @@
+import { readFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import type { Db } from '@evofw/db'
+import { repos } from '@evofw/db'
+import { AppError } from '../plugins/error-handler.js'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+const scriptsDir = join(__dirname, '../agent-scripts')
+
+const ID_ALPHABET =
+  'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789'
+
+export function randomToken(length: number): string {
+  const bytes = crypto.getRandomValues(new Uint8Array(length))
+  let out = ''
+  for (const b of bytes) {
+    out += ID_ALPHABET[b % ID_ALPHABET.length]
+  }
+  return out
+}
+
+/** Root path segments that must never be treated as install slugs. */
+export const RESERVED_ROOT_SEGMENTS = new Set([
+  'api',
+  'v1',
+  'assets',
+  'health',
+  'ready',
+  'favicon.ico',
+  'index.html',
+  'robots.txt',
+  'agent-install',
+  'static',
+])
+
+const SLUG_RE = /^[A-Za-z0-9_-]{8,64}$/
+
+export function isValidInstallSlug(segment: string): boolean {
+  if (!segment || segment.includes('/') || segment.includes('.')) return false
+  if (RESERVED_ROOT_SEGMENTS.has(segment.toLowerCase())) return false
+  return SLUG_RE.test(segment)
+}
+
+export function buildInstallUrls(baseUrl: string, id: string, slug: string) {
+  const base = baseUrl.replace(/\/$/, '')
+  const byId = `${base}/agent-install/${id}`
+  const bySlug = `${base}/${slug}`
+  return {
+    by_id: byId,
+    by_slug: bySlug,
+    curl: {
+      by_id: `curl -fsSL ${byId} | bash`,
+      by_slug: `curl -fsSL ${bySlug} | bash`,
+    },
+  }
+}
+
+export function mapInstallLink(
+  row: NonNullable<ReturnType<typeof repos.getInstallLink>>,
+  baseUrl: string,
+) {
+  const urls = buildInstallUrls(baseUrl, row.id, row.slug)
+  return {
+    id: row.id,
+    slug: row.slug,
+    client_name: row.clientName,
+    platform: row.platform as 'linux' | 'mikrotik',
+    created_at: row.createdAt,
+    revoked_at: row.revokedAt,
+    last_used_at: row.lastUsedAt,
+    use_count: row.useCount,
+    urls: { by_id: urls.by_id, by_slug: urls.by_slug },
+    curl: urls.curl,
+  }
+}
+
+function loadInstallSh(): string {
+  return readFileSync(join(scriptsDir, 'install.sh'), 'utf-8')
+}
+
+/**
+ * Self-contained install script: env exports + full install.sh body.
+ */
+export function renderInstallScript(opts: {
+  cpUrl: string
+  seed: string
+  clientName: string
+  platform: string
+}): string {
+  const cp = opts.cpUrl.replace(/\/$/, '')
+  const escape = (s: string) => s.replace(/'/g, `'\\''`)
+  const header = [
+    '#!/usr/bin/env bash',
+    '# EvoFirewall short install link — env pre-set',
+    'set -euo pipefail',
+    `export EVOFW_CP_URL='${escape(cp)}'`,
+    `export EVOFW_SEED='${escape(opts.seed)}'`,
+    `export EVOFW_CLIENT_NAME='${escape(opts.clientName)}'`,
+    `export EVOFW_PLATFORM='${escape(opts.platform)}'`,
+    '',
+  ].join('\n')
+
+  // Drop the shebang from install.sh to avoid double shebang.
+  const body = loadInstallSh().replace(/^#!\/usr\/bin\/env bash\r?\n/, '')
+  return `${header}${body}`
+}
+
+export function resolveAndRenderInstallScript(
+  db: Db,
+  link: NonNullable<ReturnType<typeof repos.getInstallLink>>,
+  publicBaseUrl: string,
+  enrollSeedFallback: string,
+): string {
+  if (link.revokedAt) {
+    throw new AppError('GONE', 'Install link revoked', 410)
+  }
+  const seed =
+    repos.getSetting(db, 'enroll_seed') || enrollSeedFallback
+  repos.touchInstallLink(db, link.id)
+  return renderInstallScript({
+    cpUrl: publicBaseUrl,
+    seed,
+    clientName: link.clientName,
+    platform: link.platform,
+  })
+}