add tailscale node delete!

.env.example

@@ -11,6 +11,8 @@ AGENT_PORT=3100
 AGENT_GATEWAY_TOKEN=
 HEADSCALE_BASE_URL=https://atnmy-hs.duckdns.org
 HEADSCALE_API_KEY=
+HEADSCALE_GATEWAY_USERS=local-platform-gateway,platform-gateway
+HEADSCALE_TEACHING_DEVICE_OWNER=tagged-devices
 LMS_GATEWAY_TOKEN=change-me
 
 # Headscale must have a policy path configured on the server for /api/v1/policy

src/config.ts

@@ -20,6 +20,11 @@ export const config = {
   agentGatewayToken: process.env.AGENT_GATEWAY_TOKEN ?? '',
   headscaleBaseUrl: required('HEADSCALE_BASE_URL', 'http://localhost:8080'),
   headscaleApiKey: process.env.HEADSCALE_API_KEY ?? '',
+  headscaleTeachingDeviceOwner: (process.env.HEADSCALE_TEACHING_DEVICE_OWNER ?? 'tagged-devices').trim().replace(/@+$/, ''),
+  headscaleGatewayUsers: (process.env.HEADSCALE_GATEWAY_USERS ?? process.env.HEADSCALE_GATEWAY_USER ?? 'local-platform-gateway')
+    .split(',')
+    .map((user) => user.trim().replace(/@+$/, ''))
+    .filter(Boolean),
   lmsGatewayToken: process.env.LMS_GATEWAY_TOKEN ?? process.env.PLATFORM_GATEWAY_TOKEN ?? '',
   launcherGatewayToken: process.env.LAUNCHER_GATEWAY_TOKEN ?? process.env.LMS_GATEWAY_TOKEN ?? process.env.PLATFORM_GATEWAY_TOKEN ?? '',
   adminGatewayToken: process.env.ADMIN_GATEWAY_TOKEN ?? process.env.PLATFORM_GATEWAY_TOKEN ?? '',

src/routes/admin.ts

@@ -20,6 +20,16 @@ adminRoutes.get('/admin/tailscale/nodes', async (c) => {
   })
 })
 
+adminRoutes.delete('/admin/tailscale/nodes/:nodeId', async (c) => {
+  const nodeId = c.req.param('nodeId').trim()
+  if (!nodeId) {
+    return c.json({ error: 'node_id_required' }, 400)
+  }
+
+  await headscaleNodeDiscovery.deleteNode(nodeId)
+  return c.json({ deleted: true, nodeId })
+})
+
 adminRoutes.get('/admin/tailscale/routes', async (c) => {
   return c.json({
     routes: await headscaleNodeDiscovery.listRouteStatus(),

src/routes/lms.ts

@@ -17,7 +17,9 @@ const sessionSchema = z.object({
     name: z.string().optional(),
     role: z.string().optional(),
   }),
-  agentOwnerEmail: z.string().email().optional(),
+  // LMS stores the Headscale user identifier here. It may be an email address
+  // or a Headscale-only username such as "tagged-devices".
+  agentOwnerEmail: z.string().trim().min(1).optional(),
   ttlSeconds: z.number().int().positive().max(8 * 60 * 60).default(config.defaultSessionTtlSeconds),
 })
 
@@ -27,6 +29,16 @@ const visualizationSchema = z.object({
   profile: z.unknown().optional(),
 })
 
+const extendSessionSchema = z.object({
+  user: z.object({
+    id: z.string().min(1),
+    email: z.string().optional(),
+    name: z.string().optional(),
+    role: z.string().optional(),
+  }),
+  ttlSeconds: z.number().int().positive().max(8 * 60 * 60),
+})
+
 const accessSyncSchema = z.object({
   assignments: z.array(z.object({
     platformId: z.string().min(1),
@@ -69,11 +81,15 @@ async function createPlatformSession(c: Context) {
       platformId: body.data.platformId,
       ttlSeconds: body.data.ttlSeconds,
       user: body.data.user as AuthUser,
+      // LMS authorizes the student against its course/group assignment before
+      // calling this route. The gateway's in-memory grants are for its own API.
+      skipAccessCheck: true,
     })
     return c.json({ session, connection: connectionPayload(platform) }, 201)
   } catch (error) {
     if (!(error instanceof Error)) throw error
     if (error.message === 'platform_not_found') return c.json({ error: error.message }, 404)
+    if (error.message === 'platform_access_denied') return c.json({ error: error.message }, 403)
     if (error.message === 'platform_busy' || error.message === 'platform_unavailable') {
       return c.json({ error: error.message }, 409)
     }
@@ -83,6 +99,26 @@ async function createPlatformSession(c: Context) {
 
 lmsRoutes.post('/lms/platform-sessions', createPlatformSession)
 
+lmsRoutes.post('/lms/platform-sessions/:platformId/extend', async (c) => {
+  const body = extendSessionSchema.safeParse(await c.req.json().catch(() => null))
+  if (!body.success) return c.json({ error: 'invalid_body', issues: body.error.flatten() }, 400)
+
+  try {
+    const session = sessionManager.extend(
+      c.req.param('platformId'),
+      body.data.user as AuthUser,
+      body.data.ttlSeconds,
+    )
+    if (!session) return c.json({ error: 'platform_session_not_found' }, 404)
+    return c.json({ session })
+  } catch (error) {
+    if (error instanceof Error && error.message === 'session_not_owned') {
+      return c.json({ error: error.message }, 403)
+    }
+    throw error
+  }
+})
+
 lmsRoutes.get('/lms/agents', async (c) => {
   const accountEmail = c.req.query('accountEmail') || undefined
   return c.json({ agents: await headscaleNodeDiscovery.listTeachingAgents(accountEmail) })
@@ -107,6 +143,8 @@ lmsRoutes.get('/lms/platforms/:id/status', async (c) => {
     sshUser: platform.sshUser ?? null,
     workspaceRoot: platform.workspaceRoot ?? null,
     lastSeenAt: platform.lastSeenAt,
+    agentStartedAt: agentHealth.startedAt ?? null,
+    agentUptimeSeconds: agentHealth.uptimeSeconds ?? null,
     state: platform.state,
     message: agentHealth.message ?? null,
   })

src/services/agent-client.ts

@@ -2,7 +2,12 @@ import { config } from '../config'
 import type { Platform } from '../types'
 
 export class AgentClient {
-  async health(platform: Platform): Promise<{ ok: boolean; message?: string }> {
+  async health(platform: Platform): Promise<{
+    ok: boolean;
+    message?: string;
+    startedAt?: string | null;
+    uptimeSeconds?: number | null;
+  }> {
     if (!platform.agentUrl) return { ok: false, message: 'platform_agent_url_missing' }
 
     const controller = new AbortController()
@@ -14,8 +19,14 @@ export class AgentClient {
         signal: controller.signal
       })
       if (!response.ok) return { ok: false, message: `agent_health_failed:${response.status}` }
-      const payload = await response.json().catch(() => ({ ok: true }))
+      const payload = await response.json().catch(() => ({ ok: true })) as Record<string, unknown>
-      return { ok: payload?.ok !== false }
+      return {
+        ok: payload?.ok !== false,
+        startedAt: typeof payload?.startedAt === 'string' ? payload.startedAt : null,
+        uptimeSeconds: typeof payload?.uptimeSeconds === 'number' && Number.isFinite(payload.uptimeSeconds)
+          ? Math.max(0, Math.floor(payload.uptimeSeconds))
+          : null,
+      }
     } catch (error) {
       return { ok: false, message: error instanceof Error ? error.message : String(error) }
     } finally {

src/services/headscale-adapter.ts

@@ -28,6 +28,7 @@ export type HeadscalePolicyStatus = {
 }
 
 const generatedPrefix = 'group:lms-platform-'
+const gatewayGroup = 'group:lms-platform-gateway'
 
 export class HeadscaleAdapter {
   async applyGrant(_grant: AccessGrant): Promise<{ applied: boolean; mode: 'noop' | 'headscale' }> {
@@ -77,8 +78,24 @@ export class HeadscaleAdapter {
   }> {
     const nodes = await this.listNodes()
     const unresolved: string[] = []
-    const groups: Record<string, string[]> = {}
+    const groups: Record<string, string[]> = {
-    const acls: HeadscalePolicy['acls'] = []
+      [gatewayGroup]: [...new Set(config.headscaleGatewayUsers.map((user) => this.toHeadscaleUserName(user)))],
+    }
+    const acls: HeadscalePolicy['acls'] = [
+      {
+        // The local bridge initiates discovery from the trusted gateway host.
+        action: 'accept',
+        src: [gatewayGroup],
+        dst: ['tag:teaching-device:*'],
+      },
+      {
+        // DDS discovery and topic payloads use independent UDP flows, so the
+        // teaching device must also be able to reach the bridge on the gateway.
+        action: 'accept',
+        src: ['tag:teaching-device'],
+        dst: [`${gatewayGroup}:*`],
+      },
+    ]
 
     assignments.forEach((assignment, index) => {
       const users = [...new Set(assignment.studentEmails.map((email) => this.toHeadscaleUserName(email)).filter(Boolean))]
@@ -103,7 +120,7 @@ export class HeadscaleAdapter {
     const policy: HeadscalePolicy = {
       groups,
       tagOwners: {
-        'tag:teaching-device': ['autogroup:admin'],
+        'tag:teaching-device': [`${config.headscaleTeachingDeviceOwner}@`],
       },
       acls,
     }
@@ -244,11 +261,11 @@ export class HeadscaleAdapter {
   }
 
   private findPlatformNode(nodes: HeadscaleNode[], assignment: AccessSyncAssignment): HeadscaleNode | null {
+    // A single instructor account can own multiple devices. ACL targets must
+    // be resolved by the platform's saved node/hostname, never by owner email.
     const tokens = [
       assignment.platformId,
-      assignment.platformName,
       assignment.agentHostname,
-      assignment.agentOwnerEmail,
     ]
       .map((value) => this.normalize(String(value ?? '')))
       .filter(Boolean)
@@ -260,19 +277,11 @@ export class HeadscaleAdapter {
         this.readString(node, 'given_name'),
         this.readString(node, 'name'),
         this.readString(node, 'hostname'),
-        this.extractUserName(node),
       ]
         .map((value) => this.normalize(value))
         .filter(Boolean)
 
-      return nodeTokens.some((nodeToken) =>
+      return nodeTokens.some((nodeToken) => tokens.includes(nodeToken))
-        tokens.some(
-          (token) =>
-            nodeToken === token ||
-            nodeToken.includes(token) ||
-            token.includes(nodeToken),
-        ),
-      )
     }) ?? null
   }
 
@@ -336,7 +345,7 @@ export class HeadscaleAdapter {
   }
 
   private toHeadscaleUserName(email: string) {
-    return this.normalize(email.replace(/@/g, '-at-')).slice(0, 63)
+    return `${this.normalize(email.replace(/@/g, '-at-')).slice(0, 63)}@`
   }
 }
 

src/services/headscale-node-discovery.ts

@@ -71,6 +71,23 @@ class HeadscaleNodeDiscovery {
     })
   }
 
+  async deleteNode(nodeId: string): Promise<void> {
+    if (!config.headscaleApiKey) {
+      throw new Error('HEADSCALE_API_KEY is not configured')
+    }
+
+    const encodedNodeId = encodeURIComponent(nodeId)
+    let response = await this.fetchHeadscale(`/api/v1/node/${encodedNodeId}`, { method: 'DELETE' })
+    if (response.status === 404) {
+      response = await this.fetchHeadscale(`/api/v1/machine/${encodedNodeId}`, { method: 'DELETE' })
+    }
+
+    if (!response.ok) {
+      const detail = await response.text().catch(() => '')
+      throw new Error(`Headscale node deletion failed (${response.status})${detail ? `: ${detail}` : ''}`)
+    }
+  }
+
   async listRouteStatus(): Promise<HeadscaleRouteStatus[]> {
     const nodes = await this.listNodes()
     return nodes.flatMap((node) => {
@@ -108,10 +125,13 @@ class HeadscaleNodeDiscovery {
 
   async resolveAgent(platform: Platform, accountEmail?: string): Promise<ResolvedAgent | null> {
     const nodes = await this.listNodes().catch(() => [])
+    // A platform binding identifies a device by its node ID or hostname. The
+    // account can own several teaching devices, so it is only a legacy fallback.
+    const platformNode = nodes.find((candidate) => this.matchesPlatform(candidate, platform))
     const accountNode = accountEmail
       ? nodes.find((candidate) => this.matchesAccount(candidate, accountEmail))
       : null
-    const node = accountNode ?? nodes.find((candidate) => this.matchesPlatform(candidate, platform))
+    const node = platformNode ?? accountNode
     if (!node) return null
 
     const ipAddress = this.extractIpAddress(node)
@@ -138,9 +158,10 @@ class HeadscaleNodeDiscovery {
     return this.extractNodeList(await response.json().catch(() => null))
   }
 
-  private fetchHeadscale(path: string) {
+  private fetchHeadscale(path: string, init?: RequestInit) {
     return fetch(`${config.headscaleBaseUrl}${path}`, {
       headers: { authorization: `Bearer ${config.headscaleApiKey}` },
+      ...init,
     })
   }
 
@@ -230,14 +251,10 @@ class HeadscaleNodeDiscovery {
       .map((value) => this.normalize(value))
       .filter(Boolean)
 
-    return nodeTokens.some((nodeToken) =>
+    // Platform bindings carry the Headscale node hostname or ID. Partial
-      platformTokens.some(
+    // matching makes a stale generic hostname such as "ubuntu" win over the
-        (platformToken) =>
+    // explicitly registered hostname (for example teacher-...-ubuntu).
-          nodeToken === platformToken ||
+    return nodeTokens.some((nodeToken) => platformTokens.includes(nodeToken))
-          nodeToken.includes(platformToken) ||
-          platformToken.includes(nodeToken),
-      ),
-    )
   }
 
   private matchesAccount(node: HeadscaleNode, accountEmail: string) {

src/services/session-manager.ts

@@ -16,13 +16,13 @@ export class SessionManager {
     return this.listActiveSessions().find((session) => session.platformId === platformId) ?? null
   }
 
-  start(input: { platformId: string; user: AuthUser; ttlSeconds: number }): PlatformSession {
+  start(input: { platformId: string; user: AuthUser; ttlSeconds: number; skipAccessCheck?: boolean }): PlatformSession {
     const platform = platformRegistry.getPlatform(input.platformId)
     if (!platform) throw new Error('platform_not_found')
     if (platform.state === 'offline' || platform.state === 'maintenance' || platform.state === 'emergency_stopped') {
       throw new Error('platform_unavailable')
     }
-    if (!accessControl.canUsePlatform(input.user, input.platformId)) {
+    if (!input.skipAccessCheck && !accessControl.canUsePlatform(input.user, input.platformId)) {
       throw new Error('platform_access_denied')
     }
     if (this.getActiveSessionByPlatform(input.platformId)) {
@@ -58,6 +58,21 @@ export class SessionManager {
     return next
   }
 
+  extend(platformId: string, user: AuthUser, ttlSeconds: number): PlatformSession | null {
+    const session = this.getActiveSessionByPlatform(platformId)
+    if (!session) return null
+    if (session.userId !== user.id && !['ADMIN', 'INSTRUCTOR'].includes(String(user.role ?? '').toUpperCase())) {
+      throw new Error('session_not_owned')
+    }
+
+    const next: PlatformSession = {
+      ...session,
+      expiresAt: new Date(Date.now() + ttlSeconds * 1000).toISOString(),
+    }
+    sessions.set(session.id, next)
+    return next
+  }
+
   markEmergencyStopped(platformId: string): PlatformSession | null {
     const session = this.getActiveSessionByPlatform(platformId)
     if (!session) return null