Skip to content

nanocoai/nanoclaw / .claude/skills/add-iron-proxy

add-iron-proxy

Flagged

Install or refresh Iron Proxy and its official Iron Control web console for NanoClaw. Use when selecting the Iron gateway, adding its management UI, configuring credentials and grants, or restoring the proxy, approval bridge, and agent guidance.

FileKindSize
REMOVE.mdmarkdown1.7 KB
SKILL.mdskill md18.4 KB
assets/entrypoint.shscript300 B
assets/managed-proxy.Dockerfileother1.0 KB
conformance/credential-scope-cases.goscript3.0 KB
conformance/credential-scope-cases.jsonconfig28.8 KB
evals/evals.jsonconfig983 B
front-proxy/go.modmanifest443 B
front-proxy/go.summanifest3.2 KB
front-proxy/main.goscript22.6 KB
front-proxy/security_test.goscript29.8 KB
gateway.jsonconfig128 B
payload/src/gateway-providers/iron-proxy-allowlist.tsscript2.9 KB
payload/src/gateway-providers/iron-proxy-approval.test.tsscript14.4 KB
payload/src/gateway-providers/iron-proxy-approval.tsscript12.2 KB
payload/src/gateway-providers/iron-proxy-credential-scope.test.tsscript23.6 KB
payload/src/gateway-providers/iron-proxy-credential-scope.tsscript14.1 KB
payload/src/gateway-providers/iron-proxy-local-model.test.tsscript2.3 KB
payload/src/gateway-providers/iron-proxy-local-model.tsscript1.8 KB
payload/src/gateway-providers/iron-proxy-transform.protoother1.4 KB
payload/src/gateway-providers/iron-proxy.test.tsscript16.5 KB
payload/src/gateway-providers/iron-proxy.tsscript21.5 KB
references/control-plane.mdmarkdown4.8 KB
scripts/allowed-hosts.test.tsscript4.0 KB
scripts/auth-resume.test.tsscript6.2 KB
scripts/auth.test.tsscript2.4 KB
scripts/auth.tsscript7.9 KB
scripts/build-managed-proxy.tsscript4.8 KB
scripts/capture-claude-token.shscript963 B
scripts/control-preflight.tsscript3.8 KB
scripts/control.test.tsscript4.5 KB
scripts/control.tsscript11.7 KB
scripts/credential-isolation.test.tsscript5.6 KB
scripts/credential-isolation.tsscript3.9 KB
scripts/credential-store.test.tsscript9.1 KB
scripts/credential-store.tsscript7.0 KB
scripts/detect.test.tsscript1.6 KB
scripts/detect.tsscript1.4 KB
scripts/install-claude.shexecutablescript1.8 KB
scripts/install-command.test.tsscript5.2 KB
scripts/install-command.tsscript4.8 KB
scripts/local-model.test.tsscript2.7 KB
scripts/provider-credentials.test.tsscript18.3 KB
scripts/provider-credentials.tsscript20.1 KB
scripts/setup.test.tsscript7.9 KB
scripts/setup.tsscript17.1 KB
versions.jsonconfig747 B

payload/src/gateway-providers/iron-proxy-approval.ts

View on GitHub
import { randomBytes } from 'node:crypto';
import fs from 'node:fs';
import path from 'node:path';

import * as grpc from '@grpc/grpc-js';
import * as protoLoader from '@grpc/proto-loader';

import { log } from '../log.js';
import { gatewayApprovalPresentation } from '../gateway-approval-presentation.js';
import { markedCut, normalizeGatewayApprovalSummary } from '../gateway-approval-summary.js';

import type { GatewayApprovalDecision, GatewayApprovalRequest } from './gateway-provider-registry.js';

export const IRON_PROXY_IDENTITY_METADATA = 'x-iron-workload-identity';
/** Set by the trusted front: "none" means no body and no protocol upgrade. */
export const IRON_PROXY_PAYLOAD_METADATA = 'x-iron-request-payload';

const CONTINUE = 1;
const REJECT = 2;

interface TransformRequest {
  method?: string;
  url?: string;
  host?: string;
}

interface TransformRequestMessage {
  request?: TransformRequest;
}

interface TransformReply {
  action: number;
  response?: { statusCode: number; body: Buffer };
}

export interface IronApprovalIdentity {
  runtimeIdentity: string;
  sessionId: string;
  agentGroupId: string;
  groupName: string;
}

export interface IronApprovalBridgeSettings {
  socketPath: string;
  /** Exact host:port pairs the front forwards over plain HTTP (a keyless local model). */
  plaintextOrigins?: readonly string[];
  timeoutMs: number;
  maxPending: number;
  protoPath?: string;
  tls?: { address: string; ca: string; cert: string; key: string };
}

interface PendingTransform {
  identity: string;
  settle: (decision: GatewayApprovalDecision) => void;
}

type IdentityResolver = (runtimeIdentity: string) => IronApprovalIdentity | undefined;
type ApprovalDecider = (request: GatewayApprovalRequest) => Promise<GatewayApprovalDecision>;

function rejection(text = 'Request denied by approval policy'): TransformReply {
  return { action: REJECT, response: { statusCode: 403, body: Buffer.from(text) } };
}

function metadataIdentity(metadata: grpc.Metadata): string | undefined {
  const values = metadata.get(IRON_PROXY_IDENTITY_METADATA);
  return values.length === 1 && typeof values[0] === 'string' && values[0].length <= 512 ? values[0] : undefined;
}

function safeRequest(
  request: TransformRequest | undefined,
  plaintextOrigins: readonly string[],
): { method: string; rawMethod: string; host: string; path: string } | undefined {
  const rawMethod = request?.method ?? '';
  const method = rawMethod.toUpperCase();
  if (!/^[A-Z]{1,16}$/.test(method)) return undefined;
  const host = (request?.host ?? '').slice(0, 253);
  if (!host || /[\0\r\n]/.test(host)) return undefined;
  try {
    // HTTP only for an exact pinned origin; anything else must stay HTTPS.
    const scheme = plaintextOrigins.includes(host.toLowerCase()) ? 'http' : 'https';
    const base = new URL(`${scheme}://${host}`);
    const url = new URL(request?.url || '/', base);
    if (url.origin !== base.origin || url.username || url.password || base.username || base.password) return undefined;
    const requestPath = markedCut(url.pathname, 240) || '/';
    return { method, rawMethod, host, path: requestPath };
  } catch {
    return undefined;
  }
}

/** Anything but one exact "none" counts as a payload, so an older front keeps every card. */
function sendsPayload(metadata: grpc.Metadata): boolean {
  const values = metadata.get(IRON_PROXY_PAYLOAD_METADATA);
  return !(values.length === 1 && values[0] === 'none');
}

function safeDisplay(value: string): string {
  return value.replace(/[<>&`]/g, '_');
}

function serviceDefinition(protoPath: string): grpc.ServiceDefinition {
  const definition = protoLoader.loadSync(protoPath, {
    defaults: true,
    enums: Number,
    longs: String,
    oneofs: true,
  });
  const loaded = grpc.loadPackageDefinition(definition) as unknown as {
    transform: { v1: { TransformService: { service: grpc.ServiceDefinition } } };
  };
  return loaded.transform.v1.TransformService.service;
}

/** Iron's gRPC transport. NanoClaw core owns the human approval workflow. */
export class IronProxyApprovalBridge {
  readonly #pending = new Map<string, PendingTransform>();
  #server: grpc.Server | null = null;
  #ready: Promise<void> | null = null;
  #decide: ApprovalDecider | null = null;

  constructor(
    readonly settings: IronApprovalBridgeSettings,
    private readonly resolveIdentity: IdentityResolver,
  ) {}

  get running(): boolean {
    return this.#server !== null;
  }

  get pendingCount(): number {
    return this.#pending.size;
  }

  async ready(): Promise<void> {
    if (!this.#ready) throw new Error('Iron Proxy approval subscription has not started');
    await this.#ready;
    if (!this.#server) throw new Error('Iron Proxy approval bridge is unavailable');
  }

  async subscribe(decide: ApprovalDecider, signal: AbortSignal): Promise<void> {
    if (this.#ready) throw new Error('Iron Proxy approval subscription already started');
    if (signal.aborted) return;
    this.#decide = decide;
    this.#ready = this.#start();
    await this.#ready;
    if (signal.aborted) {
      await this.#stop();
      return;
    }
    await new Promise<void>((resolve) => signal.addEventListener('abort', () => resolve(), { once: true }));
    await this.#stop();
  }

  cancelIdentity(runtimeIdentity: string): void {
    for (const state of this.#pending.values()) {
      if (state.identity === runtimeIdentity) state.settle('deny');
    }
  }

  async #start(): Promise<void> {
    fs.mkdirSync(path.dirname(this.settings.socketPath), { recursive: true, mode: 0o700 });
    if (!this.settings.tls) fs.rmSync(this.settings.socketPath, { force: true });
    const server = new grpc.Server({
      'grpc.max_receive_message_length': 1024 * 1024,
      'grpc.max_send_message_length': 64 * 1024,
    });
    const transformRequest: grpc.handleUnaryCall<TransformRequestMessage, TransformReply> = (call, callback) => {
      void this.#transformRequest(call).then(
        (reply) => callback(null, reply),
        (err) => {
          log.error('Iron Proxy approval transform failed closed', { err });
          callback(null, rejection('Approval bridge failed'));
        },
      );
    };
    const transformResponse: grpc.handleUnaryCall<TransformRequestMessage, TransformReply> = (call, callback) => {
      const identity = metadataIdentity(call.metadata);
      callback(null, identity && this.resolveIdentity(identity) ? { action: CONTINUE } : rejection());
    };
    server.addService(
      serviceDefinition(
        this.settings.protoPath ?? path.join(process.cwd(), 'src', 'gateway-providers', 'iron-proxy-transform.proto'),
      ),
      {
        TransformRequest: transformRequest,
        transformRequest,
        TransformResponse: transformResponse,
        transformResponse,
      },
    );
    const tls = this.settings.tls;
    const credentials = tls
      ? grpc.ServerCredentials.createSsl(
          fs.readFileSync(tls.ca),
          [{ private_key: fs.readFileSync(tls.key), cert_chain: fs.readFileSync(tls.cert) }],
          true,
        )
      : grpc.ServerCredentials.createInsecure();
    await new Promise<void>((resolve, reject) => {
      server.bindAsync(tls?.address ?? `unix:${this.settings.socketPath}`, credentials, (err) => {
        if (err) reject(err);
        else resolve();
      });
    });
    if (!tls) fs.chmodSync(this.settings.socketPath, 0o600);
    this.#server = server;
    log.info('Iron Proxy approval bridge started', {
      address: tls?.address ?? this.settings.socketPath,
      mutualTls: !!tls,
    });
  }

  async #stop(): Promise<void> {
    const server = this.#server;
    this.#server = null;
    for (const state of [...this.#pending.values()]) state.settle('deny');
    if (server) {
      await new Promise<void>((resolve) => {
        const timer = setTimeout(() => {
          server.forceShutdown();
          resolve();
        }, 5_000);
        server.tryShutdown(() => {
          clearTimeout(timer);
          resolve();
        });
      });
    }
    this.#decide = null;
    this.#ready = null;
    if (!this.settings.tls) fs.rmSync(this.settings.socketPath, { force: true });
  }

  async #transformRequest(
    call: grpc.ServerUnaryCall<TransformRequestMessage, TransformReply>,
  ): Promise<TransformReply> {
    if (!this.#server || !this.#decide) return rejection('Approval bridge unavailable');
    const runtimeIdentity = metadataIdentity(call.metadata);
    const identity = runtimeIdentity ? this.resolveIdentity(runtimeIdentity) : undefined;
    if (!runtimeIdentity || !identity) return rejection('Unknown workload identity');

    const request = safeRequest(call.request.request, this.settings.plaintextOrigins ?? []);
    if (!request) return rejection('Invalid request metadata');
    // Iron uses a synthetic CONNECT before MITM. The inner HTTP request is the
    // only approval point; Iron itself closes non-HTTP/TLS tunnel payloads.
    if (request.method === 'CONNECT') return { action: CONTINUE };
    if (this.#pending.size >= this.settings.maxPending) return rejection('Approval queue is full');

    const id = `iron-${randomBytes(10).toString('hex')}`;
    const createdAt = new Date();
    const expiresAt = new Date(createdAt.getTime() + this.settings.timeoutMs);
    const approval: GatewayApprovalRequest = {
      id,
      trigger: 'default',
      // Methods are case-sensitive upstream, so policy sees the one the front will forward.
      destination: { host: request.host, method: request.rawMethod, sendsPayload: sendsPayload(call.metadata) },
      agentGroupId: identity.agentGroupId,
      sessionId: identity.sessionId,
      runtimeIdentity: identity.runtimeIdentity,
      createdAt: createdAt.toISOString(),
      expiresAt: expiresAt.toISOString(),
      summary: {
        agent: markedCut(identity.groupName, 120),
        action: ['GET', 'HEAD'].includes(request.method)
          ? 'Read from an external service'
          : 'Send a request that may change external data',
        resource: markedCut(`${request.method} ${request.host}${request.path}`, 600),
        reason: 'No automatic approval rule covers this request. Its exact business action is unavailable.',
      },
      title: 'Network credentials request',
      question: `*Agent:* ${safeDisplay(identity.groupName.slice(0, 120))}\n*Request:* ${safeDisplay(`${request.method} ${request.host}${request.path}`)}`,
      audit: { method: request.method, host: request.host, path: request.path },
    };

    // This metadata is produced by the trusted proxy, never accepted from HTTP
    // headers. Its fields are display-only; malformed metadata fails closed.
    const summaries = call.metadata.get('x-iron-approval-summary');
    if (summaries.length) {
      try {
        if (summaries.length !== 1 || typeof summaries[0] !== 'string' || summaries[0].length > 44000)
          throw new Error();
        const summary = JSON.parse(Buffer.from(summaries[0], 'base64').toString('utf8'));
        approval.summary = normalizeGatewayApprovalSummary(
          { agent: identity.groupName, method: request.method, host: request.host, path: request.path },
          summary,
        );
        gatewayApprovalPresentation(approval);
      } catch {
        return rejection('Invalid approval summary');
      }
    }

    const decision = await new Promise<GatewayApprovalDecision>((resolve) => {
      let settled = false;
      const finish = (value: GatewayApprovalDecision) => {
        if (settled) return;
        settled = true;
        clearTimeout(timer);
        this.#pending.delete(id);
        const active = this.resolveIdentity(runtimeIdentity);
        resolve(
          active?.sessionId === identity.sessionId && active.agentGroupId === identity.agentGroupId ? value : 'deny',
        );
      };
      const timer = setTimeout(() => finish('deny'), this.settings.timeoutMs);
      const state: PendingTransform = { identity: runtimeIdentity, settle: finish };
      this.#pending.set(id, state);
      call.on('cancelled', () => finish('deny'));
      void this.#decide!(approval).then(finish, (err) => {
        log.error('Iron Proxy approval callback failed closed', { requestId: id, err });
        finish('deny');
      });
    });
    return decision === 'approve'
      ? { action: CONTINUE }
      : rejection(
          'Gateway approval was not granted. The request was denied or expired before reaching the external service. This response does not establish credential permissions.',
        );
  }
}
brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 322kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 198kUpdated Claude CodeCodexVerifiedInstall