Ios Qa

// Allowlist file at ~/.gstack/ios-qa-allowlist.json. The single source of
// truth for who can call what at which capability tier.
//
// Self-service mint over tailnet ONLY succeeds for identities present in the
// allowlist. Owner-granted mint (CLI on the Mac) is what writes new entries
// to the allowlist. Self-service mint NEVER auto-allowlists.

import { readFile, writeFile, mkdir } from 'fs/promises';
import { join, dirname } from 'path';
import { homedir } from 'os';
import type { Allowlist, AllowlistEntry, Capability } from './types';
import { capabilityCovers } from './types';

export function defaultAllowlistPath(): string {
  return process.env.GSTACK_IOS_ALLOWLIST_PATH
    ?? join(homedir(), '.gstack', 'ios-qa-allowlist.json');
}

export async function loadAllowlist(path: string = defaultAllowlistPath()): Promise<Allowlist> {
  let raw: string;
  try {
    raw = await readFile(path, 'utf-8');
  } catch (err: unknown) {
    const e = err as { code?: string };
    if (e.code === 'ENOENT') {
      return { version: 1, entries: [] };
    }
    throw err;
  }
  // Empty-file path (mktemp default, partial write, manual `: > file`): treat
  // as "no entries yet" rather than a parse error. The first grant will fill
  // it in atomically via saveAllowlist.
  if (raw.trim() === '') {
    return { version: 1, entries: [] };
  }
  const parsed = JSON.parse(raw) as Allowlist;
  if (parsed.version !== 1 || !Array.isArray(parsed.entries)) {
    throw new Error('invalid_allowlist');
  }
  return parsed;
}

export async function saveAllowlist(allowlist: Allowlist, path: string = defaultAllowlistPath()): Promise<void> {
  await mkdir(dirname(path), { recursive: true, mode: 0o700 });
  await writeFile(path, JSON.stringify(allowlist, null, 2) + '\n', { mode: 0o600 });
}

/**
 * Look up an identity in the allowlist. Returns the entry if present AND
 * not expired. Lookup is exact-match on canonicalized identity.
 */
export function findEntry(allowlist: Allowlist, identity: string): AllowlistEntry | null {
  const now = Date.now();
  for (const entry of allowlist.entries) {
    if (entry.identity !== identity) continue;
    if (entry.expires_at) {
      const exp = Date.parse(entry.expires_at);
      if (Number.isFinite(exp) && exp < now) continue;
    }
    return entry;
  }
  return null;
}

/**
 * Check whether an identity has at least the requested capability tier.
 * Returns false on missing/expired entries OR insufficient tier.
 */
export function hasCapability(allowlist: Allowlist, identity: string, need: Capability): boolean {
  const entry = findEntry(allowlist, identity);
  if (!entry) return false;
  return entry.capabilities.some(c => capabilityCovers(c, need));
}

/**
 * Owner-granted mint path. Adds (or upgrades) an allowlist entry.
 */
export async function grantIdentity(opts: {
  identity: string;
  capability: Capability;
  ttlSeconds?: number | null; // null/undefined = no expiry
  note?: string;
  path?: string;
}): Promise<Allowlist> {
  const path = opts.path ?? defaultAllowlistPath();
  const allowlist = await loadAllowlist(path);
  const existingIdx = allowlist.entries.findIndex(e => e.identity === opts.identity);
  const expiresAt = opts.ttlSeconds && opts.ttlSeconds > 0
    ? new Date(Date.now() + opts.ttlSeconds * 1000).toISOString()
    : null;
  const newEntry: AllowlistEntry = {
    identity: opts.identity,
    capabilities: [opts.capability],
    expires_at: expiresAt,
    note: opts.note,
  };
  if (existingIdx >= 0) {
    allowlist.entries[existingIdx] = newEntry;
  } else {
    allowlist.entries.push(newEntry);
  }
  await saveAllowlist(allowlist, path);
  return allowlist;
}

/**
 * Revoke an identity from the allowlist.
 */
export async function revokeIdentity(identity: string, path: string = defaultAllowlistPath()): Promise<Allowlist> {
  const allowlist = await loadAllowlist(path);
  allowlist.entries = allowlist.entries.filter(e => e.identity !== identity);
  await saveAllowlist(allowlist, path);
  return allowlist;
}

// Audit + attempts logging. Reuses the same rotation primitives as
// browse/src/tunnel-denial-log.ts (10MB rotation, 5 generations).

import { mkdir, appendFile, stat, rename, readFile } from 'fs/promises';
import { join, dirname } from 'path';
import { homedir } from 'os';
import { createHash } from 'crypto';
import type { AuditRow, AttemptRow } from './types';

const MAX_BYTES = 10 * 1024 * 1024;
const MAX_GENS = 5;

export function defaultAuditPath(): string {
  return process.env.GSTACK_IOS_AUDIT_PATH
    ?? join(homedir(), '.gstack', 'security', 'ios-qa-audit.jsonl');
}

export function defaultAttemptsPath(): string {
  return process.env.GSTACK_IOS_ATTEMPTS_PATH
    ?? join(homedir(), '.gstack', 'security', 'attempts.jsonl');
}

let _saltCache: string | null = null;

async function loadDeviceSalt(): Promise<string> {
  if (_saltCache) return _saltCache;
  const path = join(homedir(), '.gstack', 'security', 'device-salt');
  try {
    _saltCache = (await readFile(path, 'utf-8')).trim();
  } catch {
    // No salt; generate ephemeral. Real install writes one via /setup.
    const { randomBytes } = await import('crypto');
    _saltCache = randomBytes(32).toString('hex');
  }
  return _saltCache!;
}

async function rotateIfNeeded(path: string): Promise<void> {
  try {
    const s = await stat(path);
    if (s.size < MAX_BYTES) return;
  } catch {
    return; // file doesn't exist yet
  }
  // Rotate: path → path.1 → path.2 → ... → path.MAX_GENS
  for (let i = MAX_GENS - 1; i >= 0; i--) {
    const src = i === 0 ? path : `${path}.${i}`;
    const dst = `${path}.${i + 1}`;
    try {
      await rename(src, dst);
    } catch {
      // best-effort
    }
  }
}

export async function writeAudit(row: AuditRow, path: string = defaultAuditPath()): Promise<void> {
  await mkdir(dirname(path), { recursive: true, mode: 0o700 });
  await rotateIfNeeded(path);
  await appendFile(path, JSON.stringify(row) + '\n', { mode: 0o600 });
}

export async function writeAttempt(opts: {
  rawIdentity: string;
  endpoint: string;
  reason: AttemptRow['reason'];
  path?: string;
}): Promise<void> {
  const salt = await loadDeviceSalt();
  const hash = createHash('sha256').update(salt + ':' + opts.rawIdentity).digest('hex').slice(0, 16);
  const row: AttemptRow = {
    ts: new Date().toISOString(),
    identity_canon: hash,
    endpoint: opts.endpoint,
    reason: opts.reason,
  };
  const path = opts.path ?? defaultAttemptsPath();
  await mkdir(dirname(path), { recursive: true, mode: 0o700 });
  await rotateIfNeeded(path);
  await appendFile(path, JSON.stringify(row) + '\n', { mode: 0o600 });
}

// Sanitize-replacer for JSON responses — mirrors browse's sanitize-replacer.ts.
// Strips lone UTF-16 surrogate halves that would otherwise reach the
// Anthropic API as \uD800-style escapes and trigger 400.
export function sanitizeReplacer(_key: string, value: unknown): unknown {
  if (typeof value !== 'string') return value;
  // Replace lone high surrogates not followed by low surrogates, and lone
  // low surrogates not preceded by high surrogates.
  return value.replace(/[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/g, '�');
}

// /auth/mint endpoint handler. Two trust models, kept distinct:
//
// 1. Self-service mint: caller's tailnet identity (from WhoIs) must already
//    be in the allowlist. NEVER auto-allowlists.
// 2. Owner-granted mint: not on /auth/mint at all — that's the CLI
//    `gstack-ios-qa-mint --remote <identity>` writing to the allowlist file.

import { SessionTokenStore } from './session-tokens';
import { hasCapability, loadAllowlist } from './allowlist';
import { writeAttempt } from './audit';
import type { Capability } from './types';
import { capabilityCovers } from './types';

export interface MintRequest {
  capability?: Capability; // requested tier; default 'interact'
  device_udid?: string;
}

export interface MintResponse {
  session_token: string;
  expires_at: number;
  capability: Capability;
}

export interface MintError {
  error: 'identity_not_allowed' | 'capability_insufficient' | 'rate_limited';
}

export async function mintForCaller(opts: {
  callerIdentity: string;
  request: MintRequest;
  tokenStore: SessionTokenStore;
  allowlistPath?: string;
  attemptsPath?: string;
  endpoint?: string;
}): Promise<MintResponse | MintError> {
  const allowlist = await loadAllowlist(opts.allowlistPath);
  const wantedCap: Capability = opts.request.capability ?? 'interact';

  // Must be in the allowlist.
  if (!hasCapability(allowlist, opts.callerIdentity, 'observe')) {
    await writeAttempt({
      rawIdentity: opts.callerIdentity,
      endpoint: opts.endpoint ?? '/auth/mint',
      reason: 'identity_not_allowed',
      path: opts.attemptsPath,
    });
    return { error: 'identity_not_allowed' };
  }

  // Must have at least the requested capability.
  if (!hasCapability(allowlist, opts.callerIdentity, wantedCap)) {
    await writeAttempt({
      rawIdentity: opts.callerIdentity,
      endpoint: opts.endpoint ?? '/auth/mint',
      reason: 'capability_insufficient',
      path: opts.attemptsPath,
    });
    return { error: 'capability_insufficient' };
  }

  // Find the entry to determine the highest tier they can hold.
  const entry = allowlist.entries.find(e => e.identity === opts.callerIdentity);
  // Mint at the requested tier, capped at the highest granted tier.
  const grantedTier = entry?.capabilities.find(c => capabilityCovers(c, wantedCap)) ?? wantedCap;

  const result = opts.tokenStore.mint({
    identity: opts.callerIdentity,
    capability: grantedTier,
    deviceUdid: opts.request.device_udid ?? null,
    origin: 'self_service',
  });

  if ('error' in result) {
    await writeAttempt({
      rawIdentity: opts.callerIdentity,
      endpoint: opts.endpoint ?? '/auth/mint',
      reason: 'rate_limited',
      path: opts.attemptsPath,
    });
    return { error: 'rate_limited' };
  }

  return {
    session_token: result.token,
    expires_at: result.expires_at,
    capability: result.capability,
  };
}

// Owner-grant CLI. Adds (or upgrades) an identity to the allowlist so a
// remote agent on the tailnet can self-service mint a session token via
// POST /auth/mint. Never auto-allowlists; explicit user intent only.
//
// Invoked from bin/gstack-ios-qa-mint.

import { grantIdentity, revokeIdentity, loadAllowlist, defaultAllowlistPath } from './allowlist';
import type { Capability } from './types';

const CAPABILITIES: Capability[] = ['observe', 'interact', 'mutate', 'restore'];

interface ParsedArgs {
  command: 'grant' | 'revoke' | 'list' | 'help';
  identity: string | null;
  capability: Capability;
  ttlSeconds: number | null;
  note: string | null;
  path: string;
}

function parseArgs(argv: string[]): ParsedArgs {
  // Default: help. Recognized positional commands: grant | revoke | list.
  let command: ParsedArgs['command'] = 'help';
  let identity: string | null = null;
  let capability: Capability = 'interact';
  let ttlSeconds: number | null = null;
  let note: string | null = null;
  let path = defaultAllowlistPath();

  for (let i = 0; i < argv.length; i++) {
    const a = argv[i];
    switch (a) {
      case 'grant': command = 'grant'; break;
      case 'revoke': command = 'revoke'; break;
      case 'list': command = 'list'; break;
      case '--help':
      case '-h': command = 'help'; break;
      case '--remote':
      case '--identity':
        identity = argv[++i] ?? null;
        break;
      case '--capability':
      case '--cap': {
        const v = argv[++i];
        if (!CAPABILITIES.includes(v as Capability)) {
          process.stderr.write(`unknown capability: ${v} (want one of ${CAPABILITIES.join(', ')})\n`);
          process.exit(2);
        }
        capability = v as Capability;
        break;
      }
      case '--ttl': {
        const v = parseInt(argv[++i] ?? '', 10);
        if (!Number.isFinite(v) || v <= 0) {
          process.stderr.write('--ttl must be a positive integer (seconds)\n');
          process.exit(2);
        }
        ttlSeconds = v;
        break;
      }
      case '--note': note = argv[++i] ?? null; break;
      case '--allowlist-path': path = argv[++i] ?? path; break;
    }
  }
  return { command, identity, capability, ttlSeconds, note, path };
}

function printHelp() {
  const help = `gstack-ios-qa-mint — manage the tailnet allowlist for remote iOS QA agents

USAGE
  gstack-ios-qa-mint grant  --remote <identity> [--capability <tier>] [--ttl <seconds>] [--note <text>]
  gstack-ios-qa-mint revoke --remote <identity>
  gstack-ios-qa-mint list

ARGUMENTS
  --remote <identity>     Canonical tailnet identity (e.g. user@example.com or tag:ci).
  --capability <tier>     observe | interact (default) | mutate | restore
  --ttl <seconds>         Optional expiry. Omit for no-expiry entry.
  --note <text>           Free-form note kept alongside the entry.
  --allowlist-path <path> Override the allowlist file location.

EXAMPLES
  gstack-ios-qa-mint grant --remote 'alice@example.com' --capability interact
  gstack-ios-qa-mint grant --remote 'tag:ci' --capability mutate --ttl 86400 --note 'nightly run'
  gstack-ios-qa-mint revoke --remote 'alice@example.com'
  gstack-ios-qa-mint list

The allowlist lives at ~/.gstack/ios-qa-allowlist.json (mode 0600). The daemon's
self-service /auth/mint endpoint reads this file on every request.
`;
  process.stdout.write(help);
}

async function main(): Promise<void> {
  const args = parseArgs(process.argv.slice(2));

  if (args.command === 'help') {
    printHelp();
    return;
  }

  if (args.command === 'list') {
    const allowlist = await loadAllowlist(args.path);
    if (allowlist.entries.length === 0) {
      process.stdout.write('(empty allowlist)\n');
      return;
    }
    for (const e of allowlist.entries) {
      const caps = e.capabilities.join(',');
      const exp = e.expires_at ? ` expires=${e.expires_at}` : '';
      const note = e.note ? ` note="${e.note}"` : '';
      process.stdout.write(`${e.identity}  cap=${caps}${exp}${note}\n`);
    }
    return;
  }

  if (!args.identity) {
    process.stderr.write('error: --remote <identity> required\n');
    process.exit(2);
  }

  if (args.command === 'grant') {
    const result = await grantIdentity({
      identity: args.identity,
      capability: args.capability,
      ttlSeconds: args.ttlSeconds,
      note: args.note ?? undefined,
      path: args.path,
    });
    const entry = result.entries.find(e => e.identity === args.identity);
    process.stdout.write(`granted ${args.identity} capability=${args.capability}` +
      (entry?.expires_at ? ` expires=${entry.expires_at}` : '') + '\n');
    return;
  }

  if (args.command === 'revoke') {
    await revokeIdentity(args.identity, args.path);
    process.stdout.write(`revoked ${args.identity}\n`);
    return;
  }
}

if (import.meta.main) {
  main().catch((err) => {
    process.stderr.write(`gstack-ios-qa-mint: ${(err as Error).message}\n`);
    process.exit(1);
  });
}

// Thin wrappers around `xcrun devicectl` and DNS resolution. Every function
// here is unit-testable in isolation by injecting a spawnImpl + resolveImpl.
//
// Production code uses the defaults: spawnSync('xcrun', [...]) and
// dns.lookup('<host>.coredevice.local'). Tests inject stubs.

import { spawnSync, type SpawnSyncReturns } from 'child_process';
import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'fs';
import { tmpdir } from 'os';
import { join } from 'path';

export interface DeviceEntry {
  identifier: string;
  name: string;
  model: string;
  state: string; // "connected" | "available" | "available (paired)" | ...
  paired: boolean;
}

export interface SpawnImpl {
  (cmd: string, args: string[]): SpawnSyncReturns<Buffer>;
}

export interface ResolveImpl {
  (hostname: string): Promise<string[]>; // returns IPv6 addresses
}

const defaultSpawn: SpawnImpl = (cmd, args) => spawnSync(cmd, args, { stdio: 'pipe', timeout: 60_000 });

/**
 * Default resolver. Uses `dns.lookup` (getaddrinfo, goes through mDNSResponder
 * on macOS) instead of `dns.resolve6` (libresolv, does NOT consult mDNS on
 * recent macOS — returns ESERVFAIL for `*.coredevice.local`).
 *
 * Prefer the IPv6 record but fall back to whatever getaddrinfo returns.
 */
const defaultResolve: ResolveImpl = async (hostname) => {
  const dns = await import('dns');
  return new Promise((resolve, reject) => {
    dns.lookup(hostname, { family: 6, all: true }, (err, addrs) => {
      if (err) { reject(err); return; }
      const ipv6 = (addrs ?? []).filter((a) => a.family === 6).map((a) => a.address);
      if (ipv6.length === 0) { reject(new Error(`no IPv6 records for ${hostname}`)); return; }
      resolve(ipv6);
    });
  });
};

/**
 * Last-resort resolver using `dns.resolve6`. Kept for backwards compatibility
 * and for environments where mDNSResponder is not in the resolver chain. On
 * macOS 26.x (Darwin 25.x) this typically fails with ESERVFAIL — see comment
 * on `defaultResolve` above.
 */
const legacyResolve6: ResolveImpl = async (hostname) => {
  const dns = await import('dns');
  return new Promise((resolve, reject) => {
    dns.resolve6(hostname, (err, addrs) => {
      if (err) reject(err);
      else resolve(addrs);
    });
  });
};

/**
 * List devices currently known to CoreDevice. Includes connected, paired,
 * and pairing-in-progress devices.
 */
export function listDevices(spawn: SpawnImpl = defaultSpawn): DeviceEntry[] {
  const tmp = join(tmpdir(), `devicectl-list-${process.pid}-${Date.now()}.json`);
  try {
    const r = spawn('xcrun', ['devicectl', 'list', 'devices', '--json-output', tmp]);
    if (r.status !== 0) return [];
    const raw = readFileSync(tmp, 'utf-8');
    const obj = JSON.parse(raw);
    const list = (obj.result?.devices ?? []) as Array<Record<string, unknown>>;
    return list.map((d) => {
      const conn = d.connectionProperties as Record<string, unknown> | undefined;
      const props = d.deviceProperties as Record<string, unknown> | undefined;
      const hw = d.hardwareProperties as Record<string, unknown> | undefined;
      const pairingState = String(conn?.pairingState ?? '');
      return {
        identifier: String(d.identifier ?? ''),
        name: String(props?.name ?? 'unknown'),
        model: String(hw?.productType ?? 'unknown'),
        state: String(conn?.tunnelState ?? 'unknown'),
        paired: pairingState === 'paired',
      };
    });
  } catch {
    return [];
  } finally {
    try { rmSync(tmp, { force: true }); } catch { /* ignore */ }
  }
}

/**
 * Resolve the CoreDevice tunnel's IPv6 address from `devicectl device info
 * details --json-output`. This is the most reliable path on macOS 26.x: the
 * tunnel IPv6 lives in `result.connectionProperties.tunnelIPAddress` and is
 * authoritative (it's what CoreDevice itself uses to route).
 *
 * A side effect of running `devicectl device info details` is that it forces
 * CoreDevice to bring up / refresh the tunnel session, which is why we prefer
 * this over mDNS even on machines where mDNS works.
 *
 * Returns null when the device isn't found, isn't tunneled, or devicectl
 * fails — callers should fall through to mDNS resolution.
 */
export function getDeviceTunnelIPv6FromDevicectl(
  udid: string,
  spawn: SpawnImpl = defaultSpawn,
): string | null {
  const tmp = join(tmpdir(), `devicectl-details-${process.pid}-${Date.now()}.json`);
  try {
    const r = spawn('xcrun', ['devicectl', 'device', 'info', 'details', '--device', udid, '--json-output', tmp]);
    if (r.status !== 0) return null;
    const raw = readFileSync(tmp, 'utf-8');
    const obj = JSON.parse(raw);
    // `result.connectionProperties.tunnelIPAddress` is the canonical location.
    // Some Xcode/CoreDevice versions also surface it under `result.tunnel.ipAddress`
    // — accept either.
    const conn = obj?.result?.connectionProperties as Record<string, unknown> | undefined;
    const tunnel = obj?.result?.tunnel as Record<string, unknown> | undefined;
    const addr = (conn?.tunnelIPAddress ?? tunnel?.ipAddress) as string | undefined;
    if (typeof addr === 'string' && addr.includes(':')) return addr;
    return null;
  } catch {
    return null;
  } finally {
    try { rmSync(tmp, { force: true }); } catch { /* ignore */ }
  }
}

/**
 * Start a periodic devicectl `info details` poll that keeps the CoreDevice
 * tunnel session alive. Xcode 26's CoreDevice only holds the tunnel up while
 * a devicectl command is in-flight or Xcode itself is debugging. Without
 * something poking it, the tunnel IPv6 becomes unroutable within seconds —
 * `curl` to the address times out even though the address looks valid.
 *
 * Implementation note: we chose `device info details` (cheap, ~10ms of CPU
 * per tick, no persistent child process) over `device console` (which would
 * keep the tunnel up continuously but spams stdout, can wedge on backpressure,
 * and is harder to kill cleanly). The 5-second interval is comfortably under
 * the empirically-observed tunnel teardown timeout (~10-15s of idle).
 *
 * Returns a `stop()` function that cancels the timer. Safe to call multiple
 * times.
 */
export function startTunnelKeepalive(
  udid: string,
  opts: { intervalMs?: number; spawn?: SpawnImpl } = {},
): { stop: () => void } {
  const intervalMs = opts.intervalMs ?? 5_000;
  const spawn = opts.spawn ?? defaultSpawn;
  let stopped = false;
  const tick = () => {
    if (stopped) return;
    // Fire-and-forget: ignore result, the side-effect of the spawn is what
    // keeps the tunnel up. We deliberately do not use the JSON output here.
    try {
      const tmp = join(tmpdir(), `devicectl-keepalive-${process.pid}-${Date.now()}.json`);
      spawn('xcrun', ['devicectl', 'device', 'info', 'details', '--device', udid, '--json-output', tmp]);
      try { rmSync(tmp, { force: true }); } catch { /* ignore */ }
    } catch { /* ignore — next tick will retry */ }
  };
  const handle = setInterval(tick, intervalMs);
  // Don't keep the event loop alive just for this — daemon owns the lifecycle.
  if (typeof handle.unref === 'function') handle.unref();
  return {
    stop: () => {
      if (stopped) return;
      stopped = true;
      clearInterval(handle);
    },
  };
}

/**
 * Resolve the CoreDevice tunnel's IPv6 address for a device. The hostname is
 * derived from the device name as printed by `devicectl list devices`. The
 * resolved address looks like `fd72:8347:2ead::1` — RFC 4193 ULA, regenerated
 * per session.
 */
export async function getDeviceTunnelIPv6(
  deviceName: string,
  resolve: ResolveImpl = defaultResolve,
): Promise<string | null> {
  // CoreDevice mDNS host: lowercase, spaces and apostrophes → hyphens, plus
  // ".coredevice.local" suffix. Apple normalizes "Garry's Durendal" to
  // "Garrys-Durendal.coredevice.local".
  const slug = deviceName
    .replace(/['']/g, '')           // strip apostrophes
    .replace(/[\s_]+/g, '-')        // spaces/underscores → hyphens
    .replace(/[^a-zA-Z0-9-]/g, '')  // anything else not URL-safe → drop
    + '.coredevice.local';
  try {
    const addrs = await resolve(slug);
    return addrs[0] ?? null;
  } catch {
    return null;
  }
}

/**
 * Resolve a device's tunnel IPv6 using every strategy we know, in order of
 * decreasing reliability:
 *
 *   1. `devicectl device info details --json-output` (most reliable on
 *      macOS 26.x; also has the useful side-effect of bumping the tunnel).
 *   2. mDNS via `dns.lookup` (getaddrinfo path — does consult mDNSResponder
 *      on macOS, unlike `dns.resolve6`).
 *   3. mDNS via `dns.resolve6` (legacy path — kept for backwards
 *      compatibility; will ESERVFAIL on recent macOS).
 *
 * Returns the first address that any strategy yields, or null.
 */
export async function resolveTunnelIPv6(opts: {
  udid: string;
  deviceName: string;
  spawn?: SpawnImpl;
  resolve?: ResolveImpl;
  legacyResolve?: ResolveImpl;
}): Promise<string | null> {
  const spawn = opts.spawn ?? defaultSpawn;
  const resolveLookup = opts.resolve ?? defaultResolve;
  const resolveLegacy = opts.legacyResolve ?? legacyResolve6;

  // 1. devicectl-based
  const fromDevicectl = getDeviceTunnelIPv6FromDevicectl(opts.udid, spawn);
  if (fromDevicectl) return fromDevicectl;

  // 2. mDNS via dns.lookup
  const fromLookup = await getDeviceTunnelIPv6(opts.deviceName, resolveLookup);
  if (fromLookup) return fromLookup;

  // 3. last-resort: legacy dns.resolve6
  const fromLegacy = await getDeviceTunnelIPv6(opts.deviceName, resolveLegacy);
  return fromLegacy;
}

/**
 * Check whether a specific bundle ID has a running process on the device.
 */
export function isAppRunning(
  udid: string,
  bundleId: string,
  spawn: SpawnImpl = defaultSpawn,
): boolean {
  const tmp = join(tmpdir(), `devicectl-procs-${process.pid}-${Date.now()}.json`);
  try {
    const r = spawn('xcrun', ['devicectl', 'device', 'info', 'processes', '-d', udid, '--json-output', tmp]);
    if (r.status !== 0) return false;
    const raw = readFileSync(tmp, 'utf-8');
    return raw.includes(`/${bundleId}/`) || raw.includes(`/${bundleId}.app/`);
  } catch {
    return false;
  } finally {
    try { rmSync(tmp, { force: true }); } catch { /* ignore */ }
  }
}

/**
 * Launch an app on the device. Returns true on success, false otherwise.
 * Locked-device errors (the iPhone needs to be unlocked first) are surfaced
 * through the error string.
 */
export function launchApp(
  udid: string,
  bundleId: string,
  spawn: SpawnImpl = defaultSpawn,
): { ok: boolean; error?: string } {
  const r = spawn('xcrun', ['devicectl', 'device', 'process', 'launch', '--device', udid, bundleId]);
  if (r.status === 0) return { ok: true };
  const err = (r.stderr?.toString() ?? '') + (r.stdout?.toString() ?? '');
  if (err.includes('was not, or could not be, unlocked')) {
    return { ok: false, error: 'device_locked' };
  }
  if (err.includes('FBSOpenApplicationServiceErrorDomain')) {
    return { ok: false, error: 'launch_failed' };
  }
  return { ok: false, error: err.split('\n')[0] ?? 'unknown' };
}

/**
 * Copy a file out of an app's data container. Used to scrape the boot token
 * from `tmp/gstack-ios-qa.token` after the StateServer starts.
 */
export function copyFileFromAppContainer(opts: {
  udid: string;
  bundleId: string;
  sourceRelativePath: string;
  spawn?: SpawnImpl;
}): string | null {
  const spawn = opts.spawn ?? defaultSpawn;
  const dir = mkdtempSync(join(tmpdir(), 'gstack-ios-copy-'));
  const dest = join(dir, 'fetched');
  try {
    const r = spawn('xcrun', [
      'devicectl', 'device', 'copy', 'from',
      '--device', opts.udid,
      '--domain-type', 'appDataContainer',
      '--domain-identifier', opts.bundleId,
      '--source', opts.sourceRelativePath,
      '--destination', dest,
    ]);
    if (r.status !== 0) return null;
    return readFileSync(dest, 'utf-8').replace(/[\r\n]+$/, '');
  } catch {
    return null;
  } finally {
    try { rmSync(dir, { recursive: true, force: true }); } catch { /* ignore */ }
  }
}

/**
 * Install an .app bundle on the device. The bundle must be signed with a
 * dev/distribution profile that includes the device.
 */
export function installApp(
  udid: string,
  appBundlePath: string,
  spawn: SpawnImpl = defaultSpawn,
): { ok: boolean; error?: string } {
  const r = spawn('xcrun', ['devicectl', 'device', 'install', 'app', '--device', udid, appBundlePath]);
  if (r.status === 0) return { ok: true };
  return { ok: false, error: (r.stderr?.toString() ?? r.stdout?.toString() ?? 'unknown').split('\n')[0] };
}

// gstack-ios-qa-daemon entrypoint.
//
// Two listeners:
//   - Loopback (127.0.0.1 + ::1): full command surface for the spawning agent.
//   - Tailnet (optional, --tailnet flag): capability-tier allowlist.
//
// The tailnet listener is opened ONLY if:
//   1. The user passed --tailnet at the CLI.
//   2. The tailscaled LocalAPI socket probe succeeds (fail-closed otherwise).
//
// All tailnet ingress is auth-gated against the SessionTokenStore. Identity
// validation uses tailscaled's WhoIs endpoint. Capability tiers come from
// types.ts. Audit + attempts logging is in audit.ts.

import { createServer, IncomingMessage, ServerResponse } from 'http';
import { parse as parseUrl } from 'url';
import { tryClaim } from './single-instance';
import { probeTailscale, whoIs } from './tailscale-localapi';
import { SessionTokenStore } from './session-tokens';
import { mintForCaller } from './auth-mint';
import { classifyRoute, proxyToDevice, type DeviceTunnel } from './proxy';
import { writeAudit, writeAttempt, sanitizeReplacer } from './audit';
import { bootstrapTunnel } from './tunnel-bootstrap';
import { startTunnelKeepalive } from './devicectl';
import type { Capability } from './types';

interface DaemonOptions {
  loopbackPort: number;
  tailnetEnabled: boolean;
  tailnetSocketPath?: string;
  tailnetSessionTtlSeconds?: number;
  pidfilePath?: string;
  // Explicit security-log + allowlist paths. Default to the env-var-derived
  // locations (defaultAuditPath etc.) when omitted, but passing them lets
  // concurrent test instances stay isolated without racing on process.env.
  auditPath?: string;
  attemptsPath?: string;
  allowlistPath?: string;
  // Test injection
  tunnelProvider?: () => Promise<DeviceTunnel | null>;
  whoIsImpl?: (addr: string) => Promise<{ identity: string; raw: unknown }>;
  probeImpl?: () => Promise<{ ok: boolean; reason?: string; ownIdentity?: string }>;
}

export interface RunningDaemon {
  loopbackPort: number;
  tailnetPort: number | null;
  tokenStore: SessionTokenStore;
  close: () => Promise<void>;
}

export async function startDaemon(opts: DaemonOptions): Promise<RunningDaemon | { error: string; reason?: string }> {
  // 1. Single-instance enforcement.
  const claim = await tryClaim({ port: opts.loopbackPort, path: opts.pidfilePath });
  if (!claim.claimed) {
    // Existing daemon — print READY with the existing port and exit.
    // The spawnAndWaitReady caller will receive this and connect to the
    // existing port instead.
    process.stdout.write(`READY: port=${claim.existing.port} pid=${claim.existing.pid}\n`);
    return { error: 'already_running', reason: `existing daemon pid=${claim.existing.pid}` };
  }

  const tokenStore = new SessionTokenStore();
  let tunnel: DeviceTunnel | null = null;
  let cachedTunnelAt = 0;

  const getTunnel = async (): Promise<DeviceTunnel | null> => {
    // Cache the tunnel for 30s; refresh on demand.
    if (tunnel && Date.now() - cachedTunnelAt < 30_000) return tunnel;
    if (opts.tunnelProvider) {
      tunnel = await opts.tunnelProvider();
      cachedTunnelAt = Date.now();
    }
    return tunnel;
  };

  // 2. Tailnet probe (fail-closed).
  const probe = opts.tailnetEnabled
    ? (opts.probeImpl ? await opts.probeImpl() : await probeTailscale(opts.tailnetSocketPath))
    : null;

  if (opts.tailnetEnabled && (!probe || !probe.ok)) {
    process.stderr.write(`tailnet binding refused: ${probe?.reason ?? 'probe_failed'}\n`);
    // Loopback still runs.
  }

  // 3. Loopback listener (full surface).
  const loopbackServer = createServer(async (req, res) => {
    await handleLoopback({ req, res, tokenStore, getTunnel });
  });
  // Use port 0 for OS-assigned port when test/random port collisions are a risk.
  const requestedPort = opts.loopbackPort;
  await listenAsync(loopbackServer, requestedPort, '127.0.0.1');
  const actualPort = (loopbackServer.address() as { port: number }).port;

  // ipv6 — bind a SECOND server to ::1 on the same actualPort. In test (port 0)
  // mode this can collide; we try the actualPort first and skip ipv6 if it
  // fails (tests don't exercise ::1 explicitly).
  const loopbackServerV6 = createServer(async (req, res) => {
    await handleLoopback({ req, res, tokenStore, getTunnel });
  });
  let v6Bound = false;
  try {
    await listenAsync(loopbackServerV6, actualPort, '::1');
    v6Bound = true;
  } catch {
    // IPv6 loopback bind failed (port collision or no v6 on host). Loopback
    // IPv4 already serves the spawning agent. Continue.
  }

  // 4. Tailnet listener (if probe succeeded).
  let tailnetServer: ReturnType<typeof createServer> | null = null;
  let tailnetPort: number | null = null;
  if (opts.tailnetEnabled && probe?.ok) {
    tailnetServer = createServer(async (req, res) => {
      await handleTailnet({
        req,
        res,
        tokenStore,
        getTunnel,
        auditPath: opts.auditPath,
        attemptsPath: opts.attemptsPath,
        allowlistPath: opts.allowlistPath,
        whoIsImpl: opts.whoIsImpl ?? ((addr) => whoIs(addr, opts.tailnetSocketPath)),
      });
    });
    const tailnetBindAddr = process.env.GSTACK_IOS_TAILNET_BIND ?? '127.0.0.1';
    // For tailnet port: actualPort + 1 if specified, else port 0 (OS-assigned).
    const requestedTailnetPort = requestedPort === 0 ? 0 : actualPort + 1;
    await listenAsync(tailnetServer, requestedTailnetPort, tailnetBindAddr);
    tailnetPort = (tailnetServer.address() as { port: number }).port;
  }

  // 5. READY line.
  process.stdout.write(`READY: port=${actualPort} pid=${process.pid}\n`);

  return {
    loopbackPort: actualPort,
    tailnetPort,
    tokenStore,
    close: async () => {
      // Force-close any open connections (keep-alive sockets) before waiting
      // for the listening socket itself. Otherwise close() hangs forever on
      // idle clients.
      const closeAll = (s: ReturnType<typeof createServer> | null | undefined) => {
        if (!s) return Promise.resolve();
        (s as unknown as { closeAllConnections?: () => void }).closeAllConnections?.();
        (s as unknown as { closeIdleConnections?: () => void }).closeIdleConnections?.();
        return new Promise<void>((resolve) => s.close(() => resolve()));
      };
      await Promise.all([
        closeAll(loopbackServer),
        v6Bound ? closeAll(loopbackServerV6) : Promise.resolve(),
        closeAll(tailnetServer),
      ]);
      await claim.release();
    },
  };
}

function listenAsync(server: ReturnType<typeof createServer>, port: number, host: string): Promise<void> {
  return new Promise((resolve, reject) => {
    const onError = (err: Error) => {
      server.off('listening', onListening);
      reject(err);
    };
    const onListening = () => {
      server.off('error', onError);
      resolve();
    };
    server.once('error', onError);
    server.once('listening', onListening);
    server.listen(port, host);
  });
}

// ───────── Handlers ─────────

interface HandlerCtx {
  req: IncomingMessage;
  res: ServerResponse;
  tokenStore: SessionTokenStore;
  getTunnel: () => Promise<DeviceTunnel | null>;
  // Explicit security-log + allowlist paths (default to env-derived when undefined).
  auditPath?: string;
  attemptsPath?: string;
  allowlistPath?: string;
}

function readBody(req: IncomingMessage, maxBytes = 1_048_576): Promise<Buffer | { error: 'body_too_large' }> {
  return new Promise((resolve, reject) => {
    const chunks: Buffer[] = [];
    let total = 0;
    let overLimit = false;
    req.on('data', (chunk: Buffer) => {
      total += chunk.length;
      if (total > maxBytes && !overLimit) {
        overLimit = true;
      }
      if (!overLimit) chunks.push(chunk);
    });
    req.on('end', () => {
      if (overLimit) {
        resolve({ error: 'body_too_large' });
      } else {
        resolve(Buffer.concat(chunks));
      }
    });
    req.on('error', (err) => {
      // Resolve with empty body if upstream cut us off after limit hit.
      if (overLimit) resolve({ error: 'body_too_large' });
      else reject(err);
    });
  });
}

function sendJson(res: ServerResponse, status: number, body: unknown): void {
  const payload = JSON.stringify(body, sanitizeReplacer);
  res.writeHead(status, {
    'content-type': 'application/json',
    'content-length': Buffer.byteLength(payload),
  });
  res.end(payload);
}

/**
 * Loopback handler — full surface for the spawning agent. No auth (the
 * loopback bind itself is the boundary).
 */
async function handleLoopback(ctx: HandlerCtx): Promise<void> {
  const { req, res, tokenStore, getTunnel } = ctx;
  const url = parseUrl(req.url ?? '/');
  const path = url.pathname ?? '/';
  const method = req.method ?? 'GET';

  try {
    // /healthz — public on loopback.
    if (method === 'GET' && path === '/healthz') {
      sendJson(res, 200, { version: '1.0.0', mode: 'loopback' });
      return;
    }

    // /auth/sessions — list active sessions (owner only).
    if (method === 'GET' && path === '/auth/sessions') {
      sendJson(res, 200, { sessions: tokenStore.list() });
      return;
    }

    // /auth/revoke — revoke a token.
    if (method === 'POST' && path === '/auth/revoke') {
      const body = await readBody(req);
      if ('error' in body) { sendJson(res, 413, body); return; }
      const parsed = JSON.parse(body.toString('utf-8') || '{}') as { token?: string; identity?: string };
      let count = 0;
      if (parsed.token) {
        count = tokenStore.revoke(parsed.token) ? 1 : 0;
      } else if (parsed.identity) {
        count = tokenStore.revokeByIdentity(parsed.identity);
      }
      sendJson(res, 200, { revoked: count });
      return;
    }

    // Other endpoints — proxy to the device.
    const tunnel = await getTunnel();
    if (!tunnel) {
      sendJson(res, 503, { error: 'device_not_connected' });
      return;
    }
    const body = await readBody(req);
    if ('error' in body) { sendJson(res, 413, body); return; }
    const sessionId = (req.headers['x-session-id'] as string | undefined) ?? null;
    const agentIdentity = (req.headers['x-agent-identity'] as string | undefined) ?? undefined;
    const upstream = await proxyToDevice({ inbound: req, body, tunnel, sessionId, agentIdentity });
    res.writeHead(upstream.status, upstream.headers);
    res.end(upstream.body);
  } catch (err) {
    sendJson(res, 500, { error: 'internal_error', detail: (err as Error).message });
  }
}

interface TailnetCtx extends HandlerCtx {
  whoIsImpl: (addr: string) => Promise<{ identity: string; raw: unknown }>;
}

/**
 * Tailnet handler — locked allowlist + capability tiers.
 */
async function handleTailnet(ctx: TailnetCtx): Promise<void> {
  const { req, res, tokenStore, getTunnel, whoIsImpl, auditPath, attemptsPath, allowlistPath } = ctx;
  const url = parseUrl(req.url ?? '/');
  const path = url.pathname ?? '/';
  const method = req.method ?? 'GET';
  const route = `${method} ${path}`;

  try {
    // Classify the route.
    const classification = classifyRoute(method, path);
    if (!classification.allowed) {
      sendJson(res, 404, { error: 'endpoint_not_in_tailnet_allowlist', path });
      return;
    }
    const requiredCapability = classification.requiredCapability as Capability;

    // /healthz on tailnet requires auth (codex catch).
    // No special-case; treated like every other observe-tier endpoint.

    // /auth/mint — special path. No bearer required; uses WhoIs.
    if (method === 'POST' && path === '/auth/mint') {
      const peerAddr = `${req.socket.remoteAddress}:${req.socket.remotePort}`;
      let callerIdentity: string;
      try {
        const who = await whoIsImpl(peerAddr);
        callerIdentity = who.identity;
      } catch (err) {
        await writeAttempt({
          rawIdentity: peerAddr,
          endpoint: route,
          reason: 'whois_unparseable',
          path: attemptsPath,
        });
        sendJson(res, 502, { error: 'whois_failed', detail: (err as Error).message });
        return;
      }

      const body = await readBody(req);
      if ('error' in body) { sendJson(res, 413, body); return; }
      const parsed = JSON.parse(body.toString('utf-8') || '{}') as { capability?: Capability; device_udid?: string };

      const result = await mintForCaller({
        callerIdentity,
        request: parsed,
        tokenStore,
        endpoint: route,
        allowlistPath,
        attemptsPath,
      });

      if ('error' in result) {
        const status = result.error === 'rate_limited' ? 429 : 403;
        sendJson(res, status, result);
        return;
      }
      sendJson(res, 200, result);
      return;
    }

    // All other endpoints: bearer auth + capability check.
    const auth = req.headers['authorization'] as string | undefined;
    const token = auth?.startsWith('Bearer ') ? auth.slice('Bearer '.length) : null;
    const validation = tokenStore.validate(token, requiredCapability);
    if (!validation.ok) {
      await writeAttempt({
        rawIdentity: token ? 'token:' + token.slice(0, 8) : 'no_token',
        endpoint: route,
        reason: validation.reason,
        path: attemptsPath,
      });
      const status = validation.reason === 'capability_insufficient' ? 403 : 401;
      sendJson(res, status, { error: validation.reason });
      return;
    }

    const session = validation.session;

    // Read body once + enforce limit.
    const body = await readBody(req);
    if ('error' in body) { sendJson(res, 413, body); return; }

    // Tailnet-only own-session revoke.
    if (method === 'POST' && path === '/auth/revoke') {
      tokenStore.revoke(session.token);
      sendJson(res, 200, { revoked: 1 });
      return;
    }

    // Proxy to device.
    const tunnel = await getTunnel();
    if (!tunnel) {
      sendJson(res, 503, { error: 'device_not_connected' });
      return;
    }
    const sessionId = (req.headers['x-session-id'] as string | undefined) ?? null;
    const upstream = await proxyToDevice({
      inbound: req,
      body,
      tunnel,
      sessionId,
      agentIdentity: session.identity,
    });

    // Audit the action (mutating endpoints only).
    if (requiredCapability !== 'observe') {
      await writeAudit({
        ts: new Date().toISOString(),
        identity: session.identity,
        device_udid: tunnel.udid,
        endpoint: route,
        session_id: sessionId ?? '-',
        capability: session.capability,
        request_id: req.headers['x-request-id']?.toString() ?? '-',
        status: upstream.status,
      }, auditPath);
    }

    res.writeHead(upstream.status, upstream.headers);
    res.end(upstream.body);
  } catch (err) {
    sendJson(res, 500, { error: 'internal_error', detail: (err as Error).message });
  }
}

// CLI entry — runs when this file is executed directly, not when imported.
if (import.meta.main) {
  const port = parseInt(process.env.GSTACK_IOS_DAEMON_PORT ?? '9099', 10);
  const tailnet = process.argv.includes('--tailnet');
  const targetUDID = process.env.GSTACK_IOS_TARGET_UDID;
  const bundleId = process.env.GSTACK_IOS_TARGET_BUNDLE_ID ?? 'com.gstack.iosqa.fixture';

  // Default tunnelProvider: when GSTACK_IOS_TARGET_UDID (or a default with
  // any connected paired device) is set, bootstrap a real CoreDevice tunnel.
  // Otherwise return null (proxy will return 503 device_not_connected).
  //
  // After a successful bootstrap we spawn a periodic devicectl `info details`
  // call to keep the CoreDevice tunnel session alive — Xcode 26's CoreDevice
  // only holds the tunnel up while a devicectl command is in-flight, so
  // without a poke every few seconds the IPv6 becomes unroutable.
  let keepalive: { stop: () => void } | null = null;
  const realTunnelProvider = async () => {
    const result = await bootstrapTunnel({
      udid: targetUDID,
      bundleId,
    });
    if (!result.ok) {
      process.stderr.write(`bootstrap error: ${result.error}${result.detail ? ' — ' + result.detail : ''}\n`);
      return null;
    }
    if (keepalive) keepalive.stop();
    keepalive = startTunnelKeepalive(result.tunnel.udid);
    return result.tunnel;
  };

  const shutdown = () => {
    if (keepalive) { keepalive.stop(); keepalive = null; }
  };
  process.on('SIGINT', shutdown);
  process.on('SIGTERM', shutdown);
  process.on('exit', shutdown);

  startDaemon({
    loopbackPort: port,
    tailnetEnabled: tailnet,
    tunnelProvider: realTunnelProvider,
  }).then((d) => {
    if ('error' in d) {
      process.stderr.write(`daemon error: ${d.error}\n`);
      process.exit(0); // exit 0 because READY was already printed
    }
  }).catch((err) => {
    process.stderr.write(`daemon fatal: ${(err as Error).message}\n`);
    process.exit(1);
  });
}

// Tailnet → USB proxy. When an authenticated request hits the tailnet
// listener and clears capability + allowlist checks, the daemon forwards it
// to the iOS StateServer over the device's CoreDevice IPv6 tunnel, injecting
// the rotated boot token in Authorization: Bearer and preserving the
// X-Session-Id from the caller.

import { request as httpRequest } from 'http';
import type { ServerResponse, IncomingMessage } from 'http';
import { sanitizeReplacer } from './audit';
import { tierForRoute } from './types';

const MAX_BODY = 1_048_576; // 1MB hard cap on tailnet ingress

export interface DeviceTunnel {
  udid: string;
  ipv6Addr: string;
  port: number;
  bootTokenRotated: string; // the rotated bearer the daemon uses to talk to StateServer
}

export interface ProxyError {
  status: number;
  body: Record<string, unknown>;
}

/**
 * Forward a parsed inbound request to the StateServer. Returns the upstream
 * response or a ProxyError. Caller writes to the ServerResponse.
 */
export async function proxyToDevice(opts: {
  inbound: IncomingMessage;
  body: Buffer;
  tunnel: DeviceTunnel;
  sessionId: string | null;
  agentIdentity?: string;
}): Promise<{ status: number; headers: Record<string, string>; body: Buffer }> {
  const { inbound, body, tunnel, sessionId, agentIdentity } = opts;
  if (body.length > MAX_BODY) {
    return makeError(413, 'body_too_large');
  }

  const headers: Record<string, string> = {
    'authorization': `Bearer ${tunnel.bootTokenRotated}`,
    'content-type': inbound.headers['content-type'] || 'application/json',
    'content-length': String(body.length),
  };
  if (sessionId) headers['x-session-id'] = sessionId;
  if (agentIdentity) headers['x-agent-identity'] = agentIdentity;

  // Bracket IPv6 literals; pass IPv4 + hostnames bare. The CoreDevice tunnel
  // is always IPv6 in production, but tests inject 127.0.0.1 to talk to a
  // local stub. Detect by `:` count (IPv6 has multiple colons) or `:` absence
  // (IPv4/hostname).
  const isIPv6 = (tunnel.ipv6Addr.match(/:/g)?.length ?? 0) >= 2;
  const hostPart = isIPv6 ? `[${tunnel.ipv6Addr}]` : tunnel.ipv6Addr;
  const url = `http://${hostPart}:${tunnel.port}${inbound.url ?? '/'}`;
  return new Promise((resolve, reject) => {
    const req = httpRequest(url, {
      method: inbound.method,
      headers,
      timeout: 30_000,
    }, (res) => {
      const chunks: Buffer[] = [];
      res.on('data', (c) => chunks.push(c));
      res.on('end', () => {
        const respHeaders: Record<string, string> = {};
        for (const [k, v] of Object.entries(res.headers)) {
          if (typeof v === 'string') respHeaders[k] = v;
        }
        resolve({
          status: res.statusCode ?? 502,
          headers: respHeaders,
          body: Buffer.concat(chunks),
        });
      });
    });
    req.on('error', (err) => {
      const e = err as { code?: string };
      if (e.code === 'ECONNREFUSED' || e.code === 'EHOSTUNREACH') {
        resolve(makeError(503, 'device_disconnected'));
      } else if (e.code === 'ETIMEDOUT') {
        resolve(makeError(504, 'upstream_timeout'));
      } else {
        reject(err);
      }
    });
    req.write(body);
    req.end();
  });
}

function makeError(status: number, error: string): { status: number; headers: Record<string, string>; body: Buffer } {
  const body = Buffer.from(JSON.stringify({ error }, sanitizeReplacer));
  return {
    status,
    headers: { 'content-type': 'application/json', 'content-length': String(body.length) },
    body,
  };
}

/**
 * Determine whether the endpoint is allowed on the tailnet listener AND what
 * capability tier it requires.
 */
export function classifyRoute(method: string, path: string): {
  allowed: boolean;
  requiredCapability: ReturnType<typeof tierForRoute>;
} {
  const tier = tierForRoute(method, path);
  return { allowed: tier !== null, requiredCapability: tier };
}

// Short-lived session token store. In-memory only (never disk). Refreshable
// via /session/heartbeat. Listable and revokable from loopback listener.

import { randomBytes } from 'crypto';
import type { Capability, SessionToken } from './types';
import { capabilityCovers } from './types';

const TOKEN_BYTES = 32; // 256-bit
const DEFAULT_TTL_MS = 60 * 60 * 1000; // 1h per D9
const MAX_TTL_MS = 24 * 60 * 60 * 1000; // 24h hard cap

export class SessionTokenStore {
  private tokens = new Map<string, SessionToken>();
  private mintsPerIdentity = new Map<string, number[]>(); // ts (ms) for rate limiting

  constructor(
    private now: () => number = () => Date.now(),
  ) {}

  /**
   * Mint a session token. Returns null on rate limit.
   */
  mint(opts: {
    identity: string;
    capability: Capability;
    ttlMs?: number;
    deviceUdid?: string | null;
    origin: SessionToken['origin'];
  }): SessionToken | { error: 'rate_limited' } {
    if (!this.checkRateLimit(opts.identity)) {
      return { error: 'rate_limited' };
    }
    const ttl = Math.min(opts.ttlMs ?? DEFAULT_TTL_MS, MAX_TTL_MS);
    const token = randomBytes(TOKEN_BYTES).toString('base64url');
    const expires_at = this.now() + ttl;
    const session: SessionToken = {
      token,
      identity: opts.identity,
      capability: opts.capability,
      expires_at,
      device_udid: opts.deviceUdid ?? null,
      origin: opts.origin,
    };
    this.tokens.set(token, session);
    return session;
  }

  /**
   * Validate a token. Returns the session if valid (token exists, not
   * expired). Otherwise returns null with a reason for the audit log.
   */
  validate(token: string | null | undefined, need: Capability):
    | { ok: true; session: SessionToken }
    | { ok: false; reason: 'no_token' | 'invalid_token' | 'expired_token' | 'capability_insufficient' } {
    if (!token) return { ok: false, reason: 'no_token' };
    const s = this.tokens.get(token);
    if (!s) return { ok: false, reason: 'invalid_token' };
    if (s.expires_at < this.now()) {
      this.tokens.delete(token);
      return { ok: false, reason: 'expired_token' };
    }
    if (!capabilityCovers(s.capability, need)) {
      return { ok: false, reason: 'capability_insufficient' };
    }
    return { ok: true, session: s };
  }

  /**
   * Slide token expiry forward by ttlMs. Caps at the token's original max
   * (which itself is bounded by MAX_TTL_MS). Returns the new expiry.
   */
  heartbeat(token: string, ttlMs?: number): number | null {
    const s = this.tokens.get(token);
    if (!s) return null;
    if (s.expires_at < this.now()) {
      this.tokens.delete(token);
      return null;
    }
    const newExpiry = this.now() + Math.min(ttlMs ?? DEFAULT_TTL_MS, MAX_TTL_MS);
    s.expires_at = newExpiry;
    return newExpiry;
  }

  revoke(token: string): boolean {
    return this.tokens.delete(token);
  }

  revokeByIdentity(identity: string): number {
    let count = 0;
    for (const [token, s] of this.tokens) {
      if (s.identity === identity) {
        this.tokens.delete(token);
        count++;
      }
    }
    return count;
  }

  list(): SessionToken[] {
    return [...this.tokens.values()];
  }

  // For tests: clear all state.
  reset() {
    this.tokens.clear();
    this.mintsPerIdentity.clear();
  }

  /**
   * Rate limit: 10 mints / 60s per identity. Sliding window.
   */
  private checkRateLimit(identity: string): boolean {
    const now = this.now();
    const window = 60_000;
    const limit = 10;
    const hits = this.mintsPerIdentity.get(identity) ?? [];
    const recent = hits.filter(t => now - t < window);
    if (recent.length >= limit) {
      this.mintsPerIdentity.set(identity, recent);
      return false;
    }
    recent.push(now);
    this.mintsPerIdentity.set(identity, recent);
    return true;
  }
}