@amg555/frameforge-mcp 2.7.6 → 2.7.7

package/.agent/skills/gstack-browse/src/routes/pairing.ts

@@ -1,158 +0,0 @@
-/**
- * Pair-agent ceremony routes: the /connect alive probe and setup-key
- * exchange (the only unauthenticated tunnel endpoints) and root-only /pair.
- */
-
-import { json, jsonError, type RouteEntry } from './table';
-import {
-  checkConnectRateLimit, exchangeSetupKey, createSetupKey, revokeToken, revokeSetupKeys,
-  getClientSession, grantReducesAccess, assertValidClientId, assertValidTokenOptions,
-  DEFAULT_PAIR_SCOPES, InvalidScopeError, ReservedClientIdError, type ScopeCategory,
-} from '../token-registry';
-
-export const pairingRoutes: RouteEntry[] = [
-  // GET /connect — alive probe. Unauth on both surfaces. Used by /pair and
-  // /tunnel/start to detect dead ngrok tunnels via the tunnel URL, since
-  // /health is not tunnel-reachable under the dual-listener design.
-  //
-  // Shares the same rate limit as POST /connect — otherwise a tunnel caller
-  // can probe unlimited GETs, which makes the endpoint a free
-  // daemon-enumeration surface.
-  {
-    method: 'GET', path: '/connect', auth: 'none', surfaces: ['local', 'tunnel'],
-    handler: () => {
-      if (!checkConnectRateLimit()) return jsonError(429, 'Rate limited');
-      return json({ alive: true });
-    },
-  },
-
-  // ─── /connect — setup key exchange for /pair-agent ceremony ────
-  {
-    method: 'POST', path: '/connect', auth: 'none', surfaces: ['local', 'tunnel'],
-    handler: async (req) => {
-      if (!checkConnectRateLimit()) return jsonError(429, 'Too many connection attempts. Wait 1 minute.');
-      try {
-        const connectBody = await req.json() as { setup_key?: string };
-        if (!connectBody.setup_key) return jsonError(400, 'Missing setup_key');
-        const session = exchangeSetupKey(connectBody.setup_key);
-        if (!session) return jsonError(401, 'Invalid, expired, or already-used setup key');
-        console.log(`[browse] Remote agent connected: ${session.clientId} (scopes: ${session.scopes.join(',')})`);
-        return json({
-          token: session.token,
-          expires: session.expiresAt,
-          scopes: session.scopes,
-          agent: session.clientId,
-        });
-      } catch {
-        return jsonError(400, 'Invalid request body');
-      }
-    },
-  },
-
-  // ─── /pair — create setup key for pair-agent ceremony (root-only) ───
-  {
-    method: 'POST', path: '/pair', auth: 'root-token', surfaces: ['local'],
-    handler: async (req, _r, ctx) => {
-      try {
-        const pairBody = await req.json() as any;
-        // Reject a reserved/invalid clientId up front (createSetupKey enforces
-        // it too, but this makes the 400 unambiguous and skips the teardown).
-        if (pairBody.clientId !== undefined) assertValidClientId(pairBody.clientId);
-        // Default: DEFAULT_PAIR_SCOPES (full page access). The trust boundary
-        // is the pairing ceremony itself, not the scope. --control adds
-        // browser-wide destructive commands (stop, restart, disconnect).
-        // --restrict limits scope — but can never grant control: that scope
-        // stays behind the explicit control flag.
-        if (!pairBody.control && !pairBody.admin
-            && Array.isArray(pairBody.scopes) && pairBody.scopes.includes('control')) {
-          return jsonError(400, 'The control scope requires the control flag (--control); it cannot be granted via a scopes list.');
-        }
-        const scopes = pairBody.control || pairBody.admin
-          ? [...DEFAULT_PAIR_SCOPES, 'control' as const]
-          : ((pairBody.scopes || [...DEFAULT_PAIR_SCOPES]) as ScopeCategory[]);
-        // D1: a re-pair supersedes prior grants. ALWAYS drop stale setup keys
-        // so a superseded broad key can never be exchanged — this closes the
-        // shadow-key hole where a narrowing re-pair before the agent connects
-        // would otherwise leave the old broad key live. Revoke the live
-        // SESSION only when the new grant actually reduces access, so a
-        // broaden/refresh never strands a working agent mid-task. Compare
-        // against the resolved grant (not raw pairBody) so dropping 'control'
-        // or a default re-pair is classified correctly. Revoke runs BEFORE
-        // createSetupKey — revokeToken deletes all of a clientId's tokens, so
-        // minting first would nuke the fresh key.
-        const grant = {
-          scopes: [...scopes] as ScopeCategory[],
-          domains: pairBody.domains as string[] | undefined,
-          rateLimit: pairBody.rateLimit ?? 10,
-          tabPolicy: 'own-only' as const,
-        };
-        // Validate BEFORE any revoke (createSetupKey validates too, but that
-        // runs after the teardown below). A bad scope or negative rateLimit
-        // must 400 without knocking a live session offline — otherwise a
-        // reducing re-pair with a typo (--restrict red) destroys the session
-        // and mints no replacement.
-        assertValidTokenOptions(grant.scopes, grant.rateLimit);
-        const priorSession = pairBody.clientId ? getClientSession(pairBody.clientId) : null;
-        let superseded: { tokens_deleted: number; tabs_released: number } | undefined;
-        if (priorSession && grantReducesAccess(priorSession, grant)) {
-          const tokensDeleted = revokeToken(pairBody.clientId);
-          const tabsReleased = ctx.browserManager.releaseClientTabs(pairBody.clientId).length;
-          superseded = { tokens_deleted: tokensDeleted, tabs_released: tabsReleased };
-          console.log(`[browse] Superseded ${tokensDeleted} token(s), released ${tabsReleased} tab(s) for reducing re-pair: ${pairBody.clientId}`);
-        } else if (pairBody.clientId) {
-          revokeSetupKeys(pairBody.clientId);
-          // No live session, but tab ownership outlives token expiry: free any
-          // tabs orphaned by an expired session so this re-pair can't inherit
-          // an earlier incarnation's authenticated pages (mirrors DELETE
-          // /token's unconditional release). A live-session broaden keeps its
-          // tabs — the working agent still owns them.
-          if (!priorSession) ctx.browserManager.releaseClientTabs(pairBody.clientId);
-        }
-        const setupKey = createSetupKey({
-          clientId: pairBody.clientId,
-          scopes: [...scopes],
-          domains: pairBody.domains,
-          rateLimit: pairBody.rateLimit,
-        });
-        // Verify tunnel is actually alive before reporting it (ngrok may have died externally).
-        // Probe via GET /connect — under dual-listener /health is NOT on the tunnel allowlist,
-        // so the old probe would return 404 and always mark the tunnel as dead.
-        let verifiedTunnelUrl: string | null = null;
-        const tunnel = ctx.tunnel.state();
-        if (tunnel.active && tunnel.url) {
-          try {
-            const probe = await fetch(`${tunnel.url}/connect`, {
-              method: 'GET',
-              headers: { 'ngrok-skip-browser-warning': 'true' },
-              signal: AbortSignal.timeout(5000),
-            });
-            if (probe.ok) {
-              verifiedTunnelUrl = tunnel.url;
-            } else {
-              console.warn(`[browse] Tunnel probe failed (HTTP ${probe.status}), marking tunnel as dead`);
-              await ctx.tunnel.close();
-            }
-          } catch {
-            console.warn('[browse] Tunnel probe timed out or unreachable, marking tunnel as dead');
-            await ctx.tunnel.close();
-          }
-        }
-        return json({
-          setup_key: setupKey.token,
-          expires_at: setupKey.expiresAt,
-          scopes: setupKey.scopes,
-          tunnel_url: verifiedTunnelUrl,
-          server_url: `http://127.0.0.1:${ctx.browsePort}`,
-          ...(superseded ? { superseded } : {}),
-        });
-      } catch (err) {
-        // Name the caller's typo (bad scope, negative rateLimit, reserved
-        // clientId) instead of hiding it behind the generic body error.
-        if (err instanceof InvalidScopeError || err instanceof ReservedClientIdError) {
-          return jsonError(400, err.message);
-        }
-        return jsonError(400, 'Invalid request body');
-      }
-    },
-  },
-];

package/.agent/skills/gstack-browse/src/routes/pty.ts

@@ -1,254 +0,0 @@
-/**
- * Terminal (PTY) routes: session mint, re-attach, restart, dispose, lease
- * refresh from terminal-agent, and the pre-inject prompt-injection scan.
- * All are local-only: the tunnel surface 404s them by default-deny.
- */
-
-import { json, jsonError, type RouteEntry } from './table';
-import { mintPtySessionToken, buildPtySetCookie, revokePtySessionToken } from '../pty-session-cookie';
-import { mintLease, validateLease, refreshLease, revokeLease } from '../pty-session-lease';
-import { isSidecarAvailable, scanWithSidecar } from '../security-sidecar-client';
-import { sanitizeReplacer } from '../sanitize';
-
-async function readJsonOrNull(req: Request): Promise<any> {
-  try { return await req.json(); } catch { return null; }
-}
-
-export const ptyRoutes: RouteEntry[] = [
-  // ─── /pty-session — mint sessionId + lease + attachToken ─────────
-  //
-  // v1.44+ four-tuple shape:
-  //   { terminalPort, sessionId, attachToken, leaseExpiresAt }
-  //
-  //  - sessionId    : stable, non-secret. Safe to log. Identifies "this
-  //                   terminal" across re-attaches.
-  //  - attachToken  : short-lived (30 min wall, single attach in practice
-  //                   since the agent revokes on WS close). Bearer for
-  //                   the /ws upgrade.
-  //  - leaseExpiresAt: client-visible deadline for the lease. Re-attach
-  //                   only works inside this window.
-  //
-  // The lease + attachToken are minted together so a successful
-  // /pty-session is one round trip. Re-attach mints a fresh attachToken
-  // for the SAME sessionId via /pty-session/reattach.
-  {
-    method: 'POST', path: '/pty-session', auth: 'root-bearer', surfaces: ['local'],
-    handler: async (_req, _r, ctx) => {
-      const port = ctx.terminal.readPort();
-      if (!port) return jsonError(503, 'terminal-agent not ready');
-      const lease = mintLease();
-      const minted = mintPtySessionToken();
-      const granted = await ctx.terminal.grantToken(minted.token, lease.sessionId);
-      if (!granted) {
-        revokePtySessionToken(minted.token);
-        revokeLease(lease.sessionId);
-        return jsonError(503, 'failed to grant terminal session');
-      }
-      return json({
-        terminalPort: port,
-        sessionId: lease.sessionId,
-        attachToken: minted.token,
-        leaseExpiresAt: lease.expiresAt,
-        // Legacy alias — extensions still on the v1.43 wire shape keep
-        // working. Drop after one minor release once dogfood confirms.
-        ptySessionToken: minted.token,
-        expiresAt: minted.expiresAt,
-      }, { headers: { 'Set-Cookie': buildPtySetCookie(minted.token) } });
-    },
-  },
-
-  // ─── /pty-session/reattach — mint fresh attachToken for existing sessionId
-  //
-  // Validates the lease (rejects unknown/expired sessionId with 410 Gone),
-  // mints a fresh short-lived attachToken bound to the same sessionId, and
-  // pushes it to the agent. The client opens a new WS with the new token;
-  // the agent matches the sessionId binding and re-attaches to the existing
-  // PtySession (kept alive for the 60s detach window).
-  {
-    method: 'POST', path: '/pty-session/reattach', auth: 'root-bearer', surfaces: ['local'],
-    handler: async (req, _r, ctx) => {
-      const port = ctx.terminal.readPort();
-      if (!port) return jsonError(503, 'terminal-agent not ready');
-      const body = await readJsonOrNull(req);
-      const sessionId = typeof body?.sessionId === 'string' ? body.sessionId : null;
-      const v = sessionId ? validateLease(sessionId) : { ok: false as const };
-      // 410 Gone — session window has closed (lease expired or never
-      // existed). Client must fall back to /pty-session for a brand-new
-      // session.
-      if (!v.ok) return jsonError(410, 'lease expired or unknown');
-      const minted = mintPtySessionToken();
-      const granted = await ctx.terminal.grantToken(minted.token, sessionId!);
-      if (!granted) {
-        revokePtySessionToken(minted.token);
-        return jsonError(503, 'failed to grant attach token');
-      }
-      return json({
-        terminalPort: port,
-        sessionId,
-        attachToken: minted.token,
-        leaseExpiresAt: v.ok ? v.expiresAt : 0,
-      });
-    },
-  },
-
-  // ─── /pty-restart — one-transaction kill + fresh mint ────────────
-  //
-  // The Restart button. Synchronously disposes the caller's existing
-  // PtySession on the agent, revokes the old lease, mints a fresh
-  // sessionId + lease + attachToken, and returns the new 4-tuple in
-  // one response. Zero race window between kill and mint.
-  {
-    method: 'POST', path: '/pty-restart', auth: 'root-bearer', surfaces: ['local'],
-    handler: async (req, _r, ctx) => {
-      const port = ctx.terminal.readPort();
-      if (!port) return jsonError(503, 'terminal-agent not ready');
-      const body = await readJsonOrNull(req);
-      const oldSessionId = typeof body?.sessionId === 'string' ? body.sessionId : null;
-      // Best-effort dispose. Missing/unknown sessionId is non-fatal —
-      // the client may be doing a "restart from scratch" with no prior
-      // session (e.g. ENDED state). The fresh mint always proceeds.
-      if (oldSessionId) {
-        await ctx.terminal.restartSession(oldSessionId);
-        revokeLease(oldSessionId);
-      }
-      const lease = mintLease();
-      const minted = mintPtySessionToken();
-      const granted = await ctx.terminal.grantToken(minted.token, lease.sessionId);
-      if (!granted) {
-        revokePtySessionToken(minted.token);
-        revokeLease(lease.sessionId);
-        return jsonError(503, 'failed to grant terminal session');
-      }
-      return json({
-        terminalPort: port,
-        sessionId: lease.sessionId,
-        attachToken: minted.token,
-        leaseExpiresAt: lease.expiresAt,
-      });
-    },
-  },
-
-  // ─── /pty-dispose — explicit teardown (pagehide / browser quit) ──
-  //
-  // sendBeacon-compatible: accepts the auth token in the BODY so the
-  // extension's pagehide handler can fire it without setting headers
-  // (sendBeacon doesn't support custom headers). Without this, every
-  // browser quit + sidebar close leaves a zombie PTY alive for the 60s
-  // detach window.
-  {
-    method: 'POST', path: '/pty-dispose', auth: 'handler', surfaces: ['local'],
-    handlerAuth: 'root token as Authorization: Bearer or as the JSON body authToken (sendBeacon); 401 Unauthorized otherwise',
-    handler: async (req, _r, ctx) => {
-      const body = await readJsonOrNull(req);
-      const authTokenFromBody = typeof body?.authToken === 'string' ? body.authToken : null;
-      const header = req.headers.get('authorization');
-      const headerToken = header?.startsWith('Bearer ') ? header.slice(7) : null;
-      if (!ctx.isRootTokenValue(headerToken) && !ctx.isRootTokenValue(authTokenFromBody)) {
-        return jsonError(401, 'Unauthorized');
-      }
-      const sessionId = typeof body?.sessionId === 'string' ? body.sessionId : null;
-      if (sessionId) {
-        await ctx.terminal.restartSession(sessionId);
-        revokeLease(sessionId);
-      }
-      return json({ ok: true });
-    },
-  },
-
-  // ─── /internal/lease-refresh — loopback from terminal-agent on keepalive
-  //
-  // PTY-only idle reset: the headless daemon's idle timer must reset only
-  // on active PTY usage, not on every passive SSE consumer. Terminal-agent
-  // calls this endpoint (lazily, only when its cached lease is within 5 min
-  // of expiry) on its 25s keepalive cycle. Refreshing the lease here also
-  // bumps lastActivity so the daemon stays alive while a sidebar terminal
-  // is actively in use. Bound to the root authToken so an external caller
-  // can't refresh another user's lease. Body: {sessionId}.
-  {
-    method: 'POST', path: '/internal/lease-refresh', auth: 'root-bearer', surfaces: ['local'],
-    handler: async (req, _r, ctx) => {
-      const body = await readJsonOrNull(req);
-      const sessionId = typeof body?.sessionId === 'string' ? body.sessionId : null;
-      const r = sessionId ? refreshLease(sessionId) : { ok: false as const };
-      if (!r.ok) return jsonError(410, 'lease expired or unknown');
-      ctx.resetIdleTimer();
-      return json({ ok: true, expiresAt: r.expiresAt });
-    },
-  },
-
-  // ─── /pty-inject-scan — pre-inject prompt-injection scan for the
-  // extension's gstackInjectToTerminal callers. The extension routes
-  // every page-derived text through this endpoint BEFORE writing to
-  // the PTY (#1370). Sidecar absence degrades to L4 unavailable
-  // (extension shows WARN + user confirm per D7).
-  {
-    method: 'POST', path: '/pty-inject-scan', auth: 'root-bearer', surfaces: ['local'],
-    handler: async (req) => {
-      const reply = (body: unknown, status: number) => json(body, { status, replacer: sanitizeReplacer });
-      // 64KB request cap. Defense against accidentally posting an
-      // entire page DOM into the PTY path.
-      const contentLength = Number(req.headers.get('content-length') || '0');
-      if (contentLength > 64 * 1024) return reply({ error: 'payload-too-large', limit: 65536 }, 413);
-      let body: { text?: unknown; origin?: unknown } = {};
-      try {
-        body = (await req.json()) as { text?: unknown; origin?: unknown };
-      } catch {
-        return reply({ error: 'malformed-json' }, 400);
-      }
-      const text = typeof body.text === 'string' ? body.text : '';
-      if (text.length === 0) return reply({ error: 'missing-text' }, 400);
-
-      // L1-L3 honest accounting:
-      //   - URL blocklist forced to BLOCK in PTY context (override
-      //     BROWSE_CONTENT_FILTER default — page-derived text in the
-      //     REPL is a higher-risk surface than ordinary tool output).
-      //   - L4 ML classifier via the sidecar when available.
-      //   - L1-L3 envelope/datamarking is INFORMATIONAL only; the
-      //     verdict is driven by the URL blocklist + L4.
-      // See CLAUDE.md "Sidebar security stack".
-      let verdict: 'PASS' | 'WARN' | 'BLOCK' = 'PASS';
-      const reasons: string[] = [];
-
-      // Quick URL-blocklist check: text containing a known bad-actor
-      // domain → BLOCK.
-      if (/(\bbit\.ly|\btinyurl\.com|\bdiscord\.gg)/i.test(text)) {
-        verdict = 'BLOCK';
-        reasons.push('url-blocklist');
-      }
-
-      const sidecarAvail = isSidecarAvailable();
-      let l4: { available: boolean; verdict?: unknown; error?: string } = {
-        available: sidecarAvail.available,
-      };
-      if (sidecarAvail.available && verdict !== 'BLOCK') {
-        try {
-          const { verdict: layerVerdict } = await scanWithSidecar(text, { timeoutMs: 5000 });
-          l4 = { available: true, verdict: layerVerdict };
-          // LayerSignal shape: { verdict: 'safe'|'suspicious'|'unsafe', ... }
-          const lv = (layerVerdict as { verdict?: string })?.verdict;
-          if (lv === 'unsafe') {
-            verdict = 'BLOCK';
-            reasons.push('l4-unsafe');
-          } else if (lv === 'suspicious') {
-            verdict = 'WARN';
-            reasons.push('l4-suspicious');
-          }
-        } catch (err) {
-          l4 = { available: false, error: err instanceof Error ? err.message : String(err) };
-          // L4 failure during scan: degrade to WARN per D7.
-          if (verdict === 'PASS') {
-            verdict = 'WARN';
-            reasons.push('l4-unavailable');
-          }
-        }
-      } else if (!sidecarAvail.available && verdict === 'PASS') {
-        verdict = 'WARN';
-        reasons.push(`l4-unavailable:${sidecarAvail.reason ?? 'unknown'}`);
-      }
-
-      // BLOCK decisions are surfaced in the response shape; the extension
-      // logs the BLOCK event into its own activity feed on receipt.
-      return reply({ verdict, reasons, l4, datamark: '<untrusted-page-content>' }, 200);
-    },
-  },
-];

package/.agent/skills/gstack-browse/src/routes/table.ts

@@ -1,182 +0,0 @@
-/**
- * Browse route table: owns route entries, the one auth gate, the per-kind
- * denials, json()/jsonError() and the unmatched fallthrough. Moved from the
- * if-chain in server.ts buildFetchHandler; handlers live in routes/<area>.ts
- * and the ordered list is ROUTES in routes/index.ts. Add a route:
- *   { method: 'GET', path: '/thing', auth: 'root-bearer', surfaces: ['local'],
- *     handler: (req, r, ctx) => json({ ok: true }) }
- * A 'tunnel' surface also needs the TUNNEL_PATHS literal in server.ts.
- * Enforced by browse/test/server-route-dispatch-ratchet.test.ts.
- */
-
-import type { BrowserManager } from '../browser-manager';
-import type { TokenInfo } from '../token-registry';
-
-/** Which HTTP listener accepted this request. */
-export type Surface = 'local' | 'tunnel';
-
-/**
- * The check the gate runs before a handler. `handler` means the gate admits
- * the request and the handler authenticates it itself; the entry's
- * `handlerAuth` says how (used only where today's denial differs from every
- * gate kind: POST /token, POST /pty-dispose and the /cookie-picker sub-router).
- */
-export type AuthKind =
-  | 'none'
-  | 'root-bearer'
-  | 'root-token'
-  | 'scoped'
-  | 'extension-origin'
-  | 'root-or-sse-cookie'
-  | 'handler';
-
-type GatedKind = Exclude<AuthKind, 'none' | 'handler'>;
-
-/** Every gate-level denial, defined once per auth kind. */
-export const AUTH_DENIALS: Record<GatedKind, { status: number; error: string }> = {
-  'root-bearer': { status: 401, error: 'Unauthorized' },
-  'scoped': { status: 401, error: 'Unauthorized' },
-  'root-or-sse-cookie': { status: 401, error: 'Unauthorized' },
-  'root-token': { status: 403, error: 'Root token required' },
-  'extension-origin': { status: 403, error: 'Forbidden' },
-};
-
-/**
- * What handlers may use instead of closing over buildFetchHandler locals.
- * Auth arrives as check functions; the raw root token is only
- * `bootstrapRootToken`, read by POST /extension-token (returns it) and
- * /cookie-picker* (passes it to its sub-router).
- */
-export interface RouteContext {
-  browserManager: BrowserManager;
-  startTime: number;
-  browsePort: number;
-  /** Constant-time `Authorization: Bearer <cfg.authToken>` check. */
-  validateAuth(req: Request): boolean;
-  /** Bearer token equals the token registry's root token. */
-  isRootRequest(req: Request): boolean;
-  /** Root or scoped TokenInfo for the bearer token, or null. */
-  getTokenInfo(req: Request): TokenInfo | null;
-  /** The request carries a live view-only SSE session cookie. */
-  hasSseCookie(req: Request): boolean;
-  /** Origin is the pinned gstack extension and Host is loopback. */
-  isPinnedExtensionRequest(req: Request): boolean;
-  /** A token string (header or sendBeacon body) equals cfg.authToken. */
-  isRootTokenValue(token: string | null): boolean;
-  bootstrapRootToken: string;
-  resetIdleTimer(): void;
-  terminal: {
-    readPort(): number | null;
-    grantToken(token: string, sessionId?: string): Promise<boolean>;
-    restartSession(sessionId: string): Promise<boolean>;
-  };
-  tunnel: {
-    state(): { active: boolean; url: string | null; hasListener: boolean };
-    close(): Promise<void>;
-    resolveAuthtoken(): string | null;
-    start(authtoken: string): Promise<{ ok: true; url: string } | { ok: false; stage: 'bind' | 'ngrok'; error: Error }>;
-  };
-  commands: {
-    handle(body: any, tokenInfo: TokenInfo | null): Promise<Response>;
-    handleInternal(
-      body: any,
-      tokenInfo: TokenInfo | null,
-      opts: { skipRateCheck?: boolean; skipActivity?: boolean },
-    ): Promise<{ status: number; result: string; json?: boolean }>;
-  };
-}
-
-/** Per-request facts the dispatcher hands a handler. */
-export interface RouteRequest {
-  url: URL;
-  surface: Surface;
-  /** TokenInfo resolved by a 'scoped' gate; null for every other kind. */
-  tokenInfo: TokenInfo | null;
-}
-
-export type RouteHandler = (req: Request, r: RouteRequest, ctx: RouteContext) => Promise<Response> | Response;
-
-export interface RouteEntry {
-  /** HTTP method, or '*' for any method. */
-  method: string;
-  path: string;
-  /** Match every pathname starting with `path` (sub-routers). */
-  prefix?: true;
-  auth: AuthKind;
-  surfaces: readonly Surface[];
-  /** Required when auth is 'handler': where and how the handler authenticates. */
-  handlerAuth?: string;
-  handler: RouteHandler;
-}
-
-export function json(
-  body: unknown,
-  init: { status?: number; headers?: Record<string, string>; replacer?: (key: string, value: unknown) => unknown } = {},
-): Response {
-  return new Response(JSON.stringify(body, init.replacer as any), {
-    status: init.status ?? 200,
-    headers: { 'Content-Type': 'application/json', ...init.headers },
-  });
-}
-
-export function jsonError(status: number, error: string, extra: Record<string, unknown> = {}): Response {
-  return json({ error, ...extra }, { status });
-}
-
-/** Runs an entry's auth kind. Returns the resolved TokenInfo, or the kind's denial. */
-export function checkRouteAuth(auth: AuthKind, req: Request, ctx: RouteContext): { tokenInfo: TokenInfo | null } | Response {
-  const admitted = { tokenInfo: null };
-  switch (auth) {
-    case 'none':
-    case 'handler':
-      return admitted;
-    case 'root-bearer':
-      return ctx.validateAuth(req) ? admitted : deny(auth);
-    case 'root-or-sse-cookie':
-      return ctx.validateAuth(req) || ctx.hasSseCookie(req) ? admitted : deny(auth);
-    case 'root-token':
-      return ctx.isRootRequest(req) ? admitted : deny(auth);
-    case 'extension-origin':
-      return ctx.isPinnedExtensionRequest(req) ? admitted : deny(auth);
-    case 'scoped': {
-      const tokenInfo = ctx.getTokenInfo(req);
-      return tokenInfo ? { tokenInfo } : deny(auth);
-    }
-  }
-}
-
-function deny(auth: GatedKind): Response {
-  const { status, error } = AUTH_DENIALS[auth];
-  return jsonError(status, error);
-}
-
-/**
- * The declared fallthrough for a request no entry matches (unknown path, or a
- * known path with a method no entry accepts): the root-bearer check, then a
- * plain-text 404.
- */
-export const UNMATCHED_ROUTE = {
-  auth: 'root-bearer',
-  handler: () => new Response('Not found', { status: 404 }),
-} as const satisfies Pick<RouteEntry, 'auth' | 'handler'>;
-
-export function findRoute(routes: readonly RouteEntry[], method: string, pathname: string, surface: Surface): RouteEntry | null {
-  return routes.find(r =>
-    r.surfaces.includes(surface)
-    && (r.method === '*' || r.method === method)
-    && (r.prefix ? pathname.startsWith(r.path) : pathname === r.path),
-  ) ?? null;
-}
-
-export async function dispatchRoute(
-  routes: readonly RouteEntry[],
-  req: Request,
-  url: URL,
-  surface: Surface,
-  ctx: RouteContext,
-): Promise<Response> {
-  const entry = findRoute(routes, req.method, url.pathname, surface) ?? UNMATCHED_ROUTE;
-  const gate = checkRouteAuth(entry.auth, req, ctx);
-  if (gate instanceof Response) return gate;
-  return entry.handler(req, { url, surface, tokenInfo: gate.tokenInfo }, ctx);
-}

package/.agent/skills/gstack-browse/src/routes/tokens.ts

@@ -1,86 +0,0 @@
-/**
- * Scoped-token administration: mint (POST /token), revoke (the /token/*
- * sub-router, DELETE /token/:clientId) and list (GET /agents). Root-only.
- */
-
-import { json, jsonError, type RouteEntry } from './table';
-import { createToken, revokeToken, listTokens, InvalidScopeError, ReservedClientIdError } from '../token-registry';
-
-export const tokenRoutes: RouteEntry[] = [
-  // ─── /token — mint scoped tokens (root-only) ──────────────────
-  {
-    method: 'POST', path: '/token', auth: 'handler', surfaces: ['local'],
-    handlerAuth: 'root token (token registry); 403 "Only the root token can mint sub-tokens" otherwise',
-    handler: async (req, _r, ctx) => {
-      if (!ctx.isRootRequest(req)) return jsonError(403, 'Only the root token can mint sub-tokens');
-      try {
-        const tokenBody = await req.json() as any;
-        if (!tokenBody.clientId) return jsonError(400, 'Missing clientId');
-        const session = createToken({
-          clientId: tokenBody.clientId,
-          scopes: tokenBody.scopes,
-          domains: tokenBody.domains,
-          tabPolicy: tokenBody.tabPolicy,
-          rateLimit: tokenBody.rateLimit,
-          expiresSeconds: tokenBody.expiresSeconds,
-        });
-        return json({
-          token: session.token,
-          expires: session.expiresAt,
-          scopes: session.scopes,
-          agent: session.clientId,
-        });
-      } catch (err) {
-        // Name the caller's typo (bad scope, negative rateLimit, reserved
-        // clientId) instead of hiding it behind the generic body error.
-        if (err instanceof InvalidScopeError || err instanceof ReservedClientIdError) {
-          return jsonError(400, err.message);
-        }
-        return jsonError(400, 'Invalid request body');
-      }
-    },
-  },
-
-  // ─── /token/:clientId — revoke a scoped token (root-only) ─────
-  {
-    method: 'DELETE', path: '/token/', prefix: true, auth: 'root-token', surfaces: ['local'],
-    handler: (_req, { url }, ctx) => {
-      // decodeURIComponent so CLI-encoded names (spaces, UTF-8) round-trip.
-      let clientId: string;
-      try {
-        clientId = decodeURIComponent(url.pathname.slice('/token/'.length));
-      } catch {
-        return jsonError(400, 'Malformed client ID encoding');
-      }
-      const revoked = revokeToken(clientId);
-      // Release tabs UNCONDITIONALLY: ownership outlives the token (it clears
-      // only on tab close), so a client whose token already expired can still
-      // own tabs. Gating release on a revoke hit would orphan that ownership
-      // and let a same-name re-pair inherit an authenticated tab.
-      const tabsReleased = ctx.browserManager.releaseClientTabs(clientId).length;
-      if (!revoked && tabsReleased === 0) return jsonError(404, `Agent "${clientId}" not found`);
-      console.log(`[browse] Revoked ${revoked} token(s), released ${tabsReleased} tab(s) for: ${clientId}`);
-      return json({ revoked: clientId, tokens_deleted: revoked, tabs_released: tabsReleased });
-    },
-  },
-
-  // ─── /agents — list connected agents (root-only) ──────────────
-  {
-    method: 'GET', path: '/agents', auth: 'root-token', surfaces: ['local'],
-    handler: () => {
-      // includeSetup: pending (unexchanged) setup keys are live grants the
-      // operator must be able to see — without them, revoking a paired-but-
-      // never-connected agent "works" while the list shows nothing.
-      const agents = listTokens({ includeSetup: true }).map(t => ({
-        clientId: t.clientId,
-        scopes: t.scopes,
-        domains: t.domains,
-        expiresAt: t.expiresAt,
-        commandCount: t.commandCount,
-        createdAt: t.createdAt,
-        pending: t.type === 'setup',
-      }));
-      return json({ agents });
-    },
-  },
-];