​

Host Privileged Actions Contract

​

Goal

​

Current Actions

• system.clipboard.read
• system.clipboard.write
• system.hosts.write
• system.fs.mutate
• system.process.exec
• system.workflow.run

• validateHostPrivilegedActionRequest(...)
• helpers for developer UX:
  • createClipboardReadActionRequest(request)
  • createClipboardWriteActionRequest(request)
  • createFilesystemScopeCapability(scopeId)
  • createHostsWriteActionRequest(request)
  • createFilesystemMutateActionRequest(request)
  • createProcessScopeCapability(scopeId)
  • createProcessExecActionRequest(request)
  • createClipboardReadRequest(reason?)
  • createClipboardWriteRequest(text, reason?)
  • requestClipboardRead(reasonOrOptions?, options?)
  • requestClipboardWrite(text, reasonOrOptions?, options?)
  • formatPrivilegedActionError(response, options?)
  • getInlinePrivilegedActionErrorFormatterSource()

​

Request Shape

{
  action: "system.clipboard.read",
  payload: {
    reason?: string
  }
}

{
  action: "system.clipboard.write",
  payload: {
    text: string,
    reason?: string
  }
}

{
  action: "system.hosts.write",
  payload: {
    records: Array<{
      address: string;   // IPv4/IPv6
      hostname: string;  // DNS-style host token
      comment?: string;
    }>,
    dryRun?: boolean,
    tag?: string
  }
}

​

Recommended Response Envelope

type PrivilegedActionResponse =
  | { ok: true; correlationId: string; result?: unknown }
  | { ok: false; correlationId: string; error: string; code?: string };

​

Plugin-Side Usage Pattern

const request = createFilesystemMutateActionRequest({
  action: "system.fs.mutate",
  payload: {
    scope: "etc-hosts",
    dryRun: true,
    operations: [{ type: "writeFile", path: "/etc/hosts", content: "# managed", encoding: "utf8" }]
  }
});

const response = await requestPrivilegedAction(request, {
  correlationIdPrefix: "etc-hosts",
});

if (response?.ok) {
  // success path
} else {
  const message = formatPrivilegedActionError(response, {
    context: "Filesystem mutate action failed",
  });
  // deterministic error path with correlationId + error + code + process details when present
}

const formatPrivilegedActionErrorSource = getInlinePrivilegedActionErrorFormatterSource();
return `
(() => {
  const formatPrivilegedActionError = ${formatPrivilegedActionErrorSource};
  // use formatPrivilegedActionError(response, { context, fallbackCorrelationId })
})();
`;

const payload = createPrivilegedActionBackendRequest(request, {
  correlationIdPrefix: "etc-hosts",
});

import { requestPrivilegedActionFromEnvelope } from "@anikitenko/fdo-sdk";

async function runPrivilegedPipeline() {
  const envelopeOrRequest = await window.createBackendReq("UI_MESSAGE", {
    handler: "plugin.buildPrivilegedRequest",
    content: {},
  });

  const { response, errorMessage } = await requestPrivilegedActionFromEnvelope(envelopeOrRequest, {
    context: "Privileged action failed",
  });

  if (!response.ok) {
    console.error(errorMessage);
  }
}

input.result.request
input.request
direct request

const requestPayload = envelope?.result?.request ?? envelope?.request ?? envelope;
const correlationId = envelope?.result?.correlationId ?? envelope?.correlationId;

• backend handler may return { correlationId, request }
• UI_MESSAGE transport may wrap that again as { ok, result: { correlationId, request } }
• raw host privileged-action bridge should receive request
• preserve correlationId in UI diagnostics separately if you need it for fallback/error display

• passing the full backend envelope directly into requestPrivilegedAction is deprecated
• this compatibility may exist temporarily in some hosts, but SDK examples should not rely on it
• a future major release may remove compatibility for forwarding raw envelope objects

{
  action: "system.fs.mutate",
  payload: {
    scope: string, // host-defined scope id, e.g. "etc-hosts"
    operations: Array<
      | { type: "mkdir"; path: string; recursive?: boolean; mode?: number }
      | { type: "writeFile"; path: string; content: string; encoding?: "utf8" | "base64"; mode?: number }
      | { type: "appendFile"; path: string; content: string; encoding?: "utf8" | "base64" }
      | { type: "rename"; from: string; to: string }
      | { type: "remove"; path: string; recursive?: boolean; force?: boolean }
    >,
    dryRun?: boolean,
    reason?: string
  }
}

{
  action: "system.process.exec",
  payload: {
    scope: string,      // host-defined scope id, e.g. "docker-cli"
    command: string,    // absolute executable path
    args?: string[],
    cwd?: string,       // absolute path
    env?: Record<string, string>,
    timeoutMs?: number,
    input?: string,
    encoding?: "utf8" | "base64",
    dryRun?: boolean,
    reason?: string
  }
}

{
  action: "system.workflow.run",
  payload: {
    scope: string,      // host-defined scope id, e.g. "terraform"
    kind: "process-sequence",
    title: string,
    summary?: string,
    dryRun?: boolean,
    steps: Array<{
      id: string,
      title: string,
      phase?: "inspect" | "preview" | "mutate" | "apply" | "cleanup",
      command: string,  // absolute executable path
      args?: string[],
      cwd?: string,
      env?: Record<string, string>,
      timeoutMs?: number,
      input?: string,
      encoding?: "utf8" | "base64",
      reason?: string,
      onError?: "abort" | "continue"
    }>,
    confirmation?: {
      message: string,
      requiredForStepIds?: string[]
    }
  }
}

​

Capability Requirement

• For system.clipboard.read, host should require:
  • broad feature capability: system.clipboard.read
• For system.clipboard.write, host should require:
  • broad feature capability: system.clipboard.write
• Host should only execute this action when capability system.hosts.write is granted for that plugin.
• For system.fs.mutate, host should require both:
  • broad feature capability: system.hosts.write (or host-defined equivalent for privileged FS API)
  • scope capability: system.fs.scope.<scope-id>
• For system.process.exec, host should require both:
  • broad feature capability: system.process.exec
  • scope capability: system.process.scope.<scope-id>
• For system.workflow.run, first-slice host policy should reuse the same capability pair:
  • broad feature capability: system.process.exec
  • scope capability: system.process.scope.<scope-id>

​

Security Requirements For Hosts

• use the Electron clipboard API only in the trusted host process or another explicitly trusted host boundary
• do not grant plugins raw clipboard access without host mediation
• consider clipboard read more sensitive than clipboard write and gate it independently
• log/audit clipboard reads with plugin identity, correlation id, and reason when available
• log/audit clipboard writes with plugin identity, correlation id, and reason when available
• enforce explicit user confirmation for non-dry-run writes
• avoid shell interpolation; write through structured file logic
• constrain writes to /etc/hosts only
• support tagged sections to avoid uncontrolled file mutation
• log/audit each request and outcome with plugin identity and correlation id
• for system.workflow.run, log/audit:
  • workflow correlation id
  • workflow id
  • plugin identity
  • scope id
  • workflow title/kind
  • per-step stepId/title/status
  • per-step correlation id when available
  • confirmation decision for approval-gated steps
• keep an allowlist mapping from scope -> permitted absolute roots and operation types
• reject any operation whose target path is outside the mapped scope roots
• keep an allowlist mapping from scope -> permitted executable absolute paths, cwd roots, env keys, timeout policy, and argument patterns
• reject any process execution request outside the mapped command policy
• reject any workflow step outside the mapped process policy for the selected scope

​

Workflow Response Expectations

• the stable privileged response envelope with workflow-level correlationId
• a normalized workflow summary
• per-step results with typed process result data where available:
  • command
  • args
  • cwd
  • exitCode
  • stdout
  • stderr
  • durationMs
  • dryRun

• failed stepId
• failed step title
• step-level correlationId when available
• stable error and code

​

Recommended Host Scope Model

1. Define host policy scopes (for example etc-hosts, usr-local-bin), each with:
   • allowed absolute root paths
   • allowed operation set
   • confirmation policy
2. Grant plugins explicit scope capabilities using system.fs.scope.<scope-id>.
3. Evaluate every system.fs.mutate operation against the selected scope before any write.
4. Keep plugin runtime sandbox (PLUGIN_HOME) unchanged; privileged writes stay host-mediated only.

​

Docker-Style Plugin Guidance

1. Prefer system.process.exec over raw shell access.
2. Grant:
   • system.process.exec
   • system.process.scope.docker-cli
3. Host policy for docker-cli should allow only:
   • exact executable paths such as /usr/local/bin/docker or host-specific equivalents
   • approved subcommands / argument shapes
   • bounded execution time
   • explicit cwd rules
4. Do not expose unrestricted shell evaluation as a plugin capability.

​

General Operator Plugin Guidance

• Kubernetes dashboards (system.process.scope.kubectl)
• Helm managers (system.process.scope.helm)
• Terraform/operator consoles (system.process.scope.terraform)
• other serious local operations tooling

• scoped privileged actions
• exact tool-family scopes
• allowlisted binaries and argument policies

• generic shell execution
• unrestricted process spawning
• broad “admin” or “root” style plugin permissions