@stage-labs/metro 0.1.0-beta.26 → 0.1.0-beta.260

package/runtime/node_modules/@metro-labs/{mcp → daemon}/src/mcp/tool-schemas.ts

@@ -1,3 +1,6 @@
+import type { ToolDef } from './tool-def.js';
+import { attachmentItem, CREATE_UPLOAD_TOOL } from './attachment-schema.js';
+
 const lineProp = {
   type: 'string',
   description:
@@ -8,98 +11,10 @@ const msgIdProp = {
   description: 'The target message_id.',
 } as const;
 
-const attachmentItem = {
-  type: 'object',
-  description:
-    'A file to attach. Provide EXACTLY ONE source; naming two is an error and so is naming ' +
-    'none. Which one to use: `upload` for any real file on your own machine, including a ' +
-    'confidential one (call `create_upload` first, push the bytes over HTTP, then name the ' +
-    'id here); `data` ONLY for a tiny file, a few KB at most, because the base64 has to be ' +
-    'written out verbatim in this tool call and long base64 gets corrupted in the writing; ' +
-    '`url` when the file is ALREADY published somewhere the daemon can fetch it; `path` ONLY ' +
-    'for a file that is already sitting on the daemon host, which is almost never your ' +
-    'machine.',
-  properties: {
-    upload: {
-      type: 'string',
-      description:
-        'The `upload_id` of a file already pushed to metro over HTTP (`create_upload` mints ' +
-        'the slot and the one-line command; the bytes never pass through this conversation). ' +
-        'THIS IS THE ROUTE FOR ANYTHING REAL: it takes files up to 64 MiB, works for a file on ' +
-        'your own machine, and publishes nothing. The upload belongs to your agent, expires ' +
-        '30 minutes after it is created, and no other agent can name it.',
-    },
-    data: {
-      type: 'string',
-      description:
-        'Base64-encoded file bytes, inline in this call. ONLY FOR TINY FILES. The hard cap is ' +
-        '8 MiB decoded, but the real ceiling is far lower and is not enforced by the daemon: ' +
-        'this base64 has to be emitted verbatim as part of the tool call, and past roughly ' +
-        '10 KB (~13 KB of base64) it comes out corrupted, so the file arrives silently ' +
-        'damaged or fails to decode. Use `upload` instead for anything bigger. A ' +
-        '`data:<mime>;base64,` prefix is accepted and supplies the mime when `mime` is ' +
-        'omitted. Stations impose their own, lower limits (xmtp refuses non-image files over ' +
-        '~190 KiB).',
-    },
-    url: {
-      type: 'string',
-      description:
-        'http(s) URL fetched BY THE DAEMON, so it must already be publicly reachable from the ' +
-        'daemon host. Right when the file is already published; never for anything ' +
-        'confidential, because it has to be public for this to work at all. Use `upload` for ' +
-        'a confidential file.',
-    },
-    path: {
-      type: 'string',
-      description:
-        'Absolute path resolved ON THE DAEMON HOST, which is a different machine from yours. ' +
-        'A path on your own disk does NOT resolve here and is refused, however local it ' +
-        'looks. Use `upload` for a file on your machine.',
-    },
-    mime: {
-      type: 'string',
-      description: 'MIME type (guessed from the name/extension if omitted).',
-    },
-    name: {
-      type: 'string',
-      description:
-        'Filename to present (defaults to the basename, or to the name given at upload time).',
-    },
-  },
-} as const;
-
-const CREATE_UPLOAD_TOOL = {
-  name: 'create_upload',
-  description:
-    'Reserve a slot to push a file to metro over HTTP so you can attach it with `send`. Use ' +
-    'this for any file that actually matters: it is the only attachment route that carries a ' +
-    'file from YOUR machine without publishing it and without the bytes passing through this ' +
-    'conversation. Args: name? (the filename to present), mime?. Returns `upload_id`, a ' +
-    'single-use `upload_url` and a ready-to-run `curl` line. ONE STEP NEEDS A SHELL: run that ' +
-    'command (or any HTTP client) to push the bytes; there is no way to move a local file to ' +
-    'the daemon over MCP alone, because anything in an MCP call has to be written out by the ' +
-    'model first. If you have no shell, hand the single command to a subagent that does and ' +
-    'keep the `upload_id` -- the slot belongs to this metro agent, not to whoever runs the ' +
-    'command. Then: send({line, attachments:[{upload:"<upload_id>"}]}). Up to 64 MiB, expires ' +
-    '30 minutes after it is created, and no other agent can reference it.',
-  inputSchema: {
-    type: 'object',
-    properties: {
-      name: {
-        type: 'string',
-        description: 'Filename to present to the recipient (e.g. `report.pdf`).',
-      },
-      mime: {
-        type: 'string',
-        description: 'MIME type (guessed from the name/extension if omitted).',
-      },
-    },
-  },
-};
-
-export const COMMON_TOOLS = [
+export const COMMON_TOOLS: ToolDef[] = [
   {
     name: 'reply',
+    group: 'write',
     description:
       'Reply to a specific message in a Metro conversation (text quotes the target). Args: ' +
       "line, message_id, text. The station is derived from the line. Returns the daemon's " +
@@ -116,15 +31,19 @@ export const COMMON_TOOLS = [
   },
   {
     name: 'send',
+    group: 'write',
     description:
       'Send a message (and/or media) to a Metro conversation. Args: line, text?, reply_to?, ' +
-      'attachments?. The station is derived from the line. Each attachment names EXACTLY ONE ' +
+      'subject?, attachments?, frame?, wallet?. The station is derived from the line. Outlook and Gmail: send to ' +
+      'metro://<outlook|gmail>/<account>/<email address> to start a new email (subject defaults to the ' +
+      'first line of text); the result names the new thread line. Each attachment names EXACTLY ONE ' +
       'source, and the choice matters: `upload` (an `upload_id` from `create_upload`, the ' +
       'route for any real file on your own machine, confidential or not, up to 64 MiB); ' +
       '`data` (base64 inline -- TINY FILES ONLY, a few KB, because the base64 has to be ' +
       'written out verbatim in the call and longer than that it corrupts); `url` (the daemon ' +
       'fetches it, so the file must already be public); `path` (resolved on the DAEMON host, ' +
-      'which is not your machine). At least one of text/attachments is required. ' +
+      'which is not your machine). Stage (XMTP) only: `frame` posts an interactive view, `wallet` a payment ' +
+      'or signature card. At least one of text/attachments/frame/wallet is required. ' +
       'The success line names each attachment the station actually delivered; a station that ' +
       'cannot carry a file errors instead of reporting success.',
     inputSchema: {
@@ -139,17 +58,71 @@ export const COMMON_TOOLS = [
           type: 'string',
           description: 'Optional message_id to quote/reply to.',
         },
+        subject: {
+          type: 'string',
+          description: 'Outlook and Gmail only: the subject of a new email.',
+        },
         attachments: {
           type: 'array',
           description: 'Optional files to attach.',
           items: attachmentItem,
         },
+        frame: {
+          type: 'object',
+          description:
+            'Stage (XMTP) only: a frame, a small interactive view. Stage shows it in the chat at image size ' +
+            '(400 x 400 at most, its start screen, clipped with a fade) and opens it full screen on a tap; its ' +
+            'buttons work only there. `widget` is OpenAI ChatKit widget JSON (a Card, ListView ' +
+            'or Basic root, 64K characters at most); a missing `title` or `description` is taken from the ' +
+            'widget. Or give `screens` instead of `widget` for several screens in one frame. A tap there comes back ' +
+            'to you as a reply to the frame: "Frame action: <type> <payload ' +
+            "JSON>\". It is sent after the text, and the message_id returned is the frame's. The stage " +
+            'skill lists the widget nodes, with an example.',
+          properties: {
+            widget: {
+              type: 'object',
+              description:
+                'ChatKit widget JSON, e.g. {"type":"Card","children":[{"type":"Title","value":"Deploy?"},' +
+                '{"type":"Button","label":"Ship it","onClickAction":{"type":"deploy","payload":{"env":"prod"}}}]}.',
+              additionalProperties: true,
+            },
+            screens: {
+              type: 'object',
+              description:
+                'Instead of `widget`: up to 50 screens by id, each a widget or {"title", "widget"}, 64K ' +
+                'characters in all. An action {"type":"frame.open","payload":{"screen":"<id>"}} opens a ' +
+                'screen and {"type":"frame.back"} goes back, in Stage, with no message to you.',
+              additionalProperties: true,
+            },
+            start: { type: 'string', description: 'Required with `screens`: the id of the first screen.' },
+            title: { type: 'string', description: 'Card title in the chat (200 characters at most).' },
+            description: { type: 'string', description: 'Card description in the chat (1000 characters at most).' },
+          },
+        },
+        wallet: {
+          type: 'object',
+          description:
+            'Stage (XMTP) only: a wallet card. `type` walletSendCalls is a payment request with a Pay button, ' +
+            'transactionReference a payment receipt with an explorer link, signatureRequest a Sign button, ' +
+            'signatureReference a signed proof. `content` is that type\'s JSON as Stage reads it; the stage skill ' +
+            'has an example of each. Sending it moves nothing: the person taps Pay or Sign and confirms in Stage. ' +
+            "It is sent after the text and any frame, and the message_id returned is the card's.",
+          properties: {
+            type: {
+              type: 'string',
+              enum: ['walletSendCalls', 'transactionReference', 'signatureRequest', 'signatureReference'],
+            },
+            content: { type: 'object', description: 'The JSON of that content type.', additionalProperties: true },
+          },
+          required: ['type', 'content'],
+        },
       },
       required: ['line'],
     },
   },
   {
     name: 'react',
+    group: 'write',
     description:
       'Add an emoji reaction to a message. Args: line, message_id, emoji. The station is derived from the line.',
     inputSchema: {
@@ -162,8 +135,22 @@ export const COMMON_TOOLS = [
       required: ['line', 'message_id', 'emoji'],
     },
   },
+  {
+    name: 'typing',
+    group: 'write',
+    description:
+      'Show "typing…" once in a chat while you prepare an answer. The network clears it by itself after its own time (about 5 s on the Telegram bot, 10 s on Discord, 25 s on WhatsApp) or when you send. Call it again to show it again. Args: line.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        line: lineProp,
+      },
+      required: ['line'],
+    },
+  },
   {
     name: 'unreact',
+    group: 'write',
     description:
       'Remove an emoji reaction from a message. Args: line, message_id, emoji. The station is derived from the line.',
     inputSchema: {
@@ -181,6 +168,7 @@ export const COMMON_TOOLS = [
   },
   {
     name: 'edit',
+    group: 'write',
     description:
       'Edit the text of a message you sent. Args: line, message_id, text. The station is ' +
       "derived from the line. Returns the daemon's reason if the station does not support edits.",
@@ -196,6 +184,8 @@ export const COMMON_TOOLS = [
   },
   {
     name: 'delete',
+    group: 'write',
+    destructive: true,
     description:
       'Delete a message you sent. Args: line, message_id. The station is derived from the line. ' +
       "Returns the daemon's reason if the station does not support deletes.",
@@ -207,14 +197,28 @@ export const COMMON_TOOLS = [
   },
   {
     name: 'read',
+    group: 'read',
     description:
-      'Read recent message history for a conversation. Args: line, limit?, before?, since?. The ' +
-      'station is derived from the line. Returns the raw history JSON (shapes differ per ' +
-      "station), or the daemon's reason if the station does not support reads.",
+      'Read message history. Args: line?, account?, limit?, before?, since?, until?, query?, ' +
+      'from?, unread_only?, message_id?. Give a line to read one conversation, or an account ' +
+      '(from list_accounts) instead of a line to read across that whole account, where the ' +
+      'station allows it. `message_id` returns that one message in full, with its files saved ' +
+      'like inbound media (url and local_path). Each station applies the filters it supports; ' +
+      'the answer lists any it did not apply in `ignored`, so check it. Returns the raw JSON ' +
+      "(shapes differ per station), or the daemon's reason if the station does not support " +
+      'reads. Outlook: `query` is a Microsoft search over all mail (with `from` folded into it; ' +
+      'line, since, until and unread_only then narrow what the search found), and without ' +
+      '`query` every filter is applied by Outlook itself, newest first. Gmail: `query` uses ' +
+      'Gmail search syntax (from:, subject:, has:attachment, newer_than:7d...), and the other ' +
+      'filters are added to it.',
     inputSchema: {
       type: 'object',
       properties: {
         line: lineProp,
+        account: {
+          type: 'string',
+          description: 'An account id from list_accounts, to read the whole account when you give no line.',
+        },
         limit: { type: 'number', description: 'Max messages to return.' },
         before: {
           type: 'string',
@@ -224,12 +228,20 @@ export const COMMON_TOOLS = [
           type: 'string',
           description: 'Return messages since this timestamp.',
         },
+        until: {
+          type: 'string',
+          description: 'Return messages before this timestamp.',
+        },
+        query: { type: 'string', description: 'Free text to search for.' },
+        from: { type: 'string', description: 'Only messages from this sender (an id or an address).' },
+        unread_only: { type: 'boolean', description: 'Only messages not read yet.' },
+        message_id: { type: 'string', description: 'Return this one message in full.' },
       },
-      required: ['line'],
     },
   },
   {
     name: 'list_members',
+    group: 'read',
     description:
       'List the members of a Metro group/channel in a station-agnostic shape. Args: line, ' +
       'limit?. The station is derived from the line. Returns {line, station, memberCount, ' +
@@ -253,6 +265,7 @@ export const COMMON_TOOLS = [
   },
   {
     name: 'create_group',
+    group: 'write',
     description:
       'Create a new group/channel on a station and add members, in a station-agnostic shape. ' +
       'Args: station (required, xmtp|telegram|discord-bot|telegram-bot), name (required), members? ' +
@@ -292,6 +305,7 @@ export const COMMON_TOOLS = [
   },
   {
     name: 'add_members',
+    group: 'write',
     description:
       'Add members to an existing Metro group, in a station-agnostic shape. Args: line ' +
       '(required), members? (string[]; station-specific identifiers). xmtp also accepts ' +
@@ -324,6 +338,8 @@ export const COMMON_TOOLS = [
   },
   {
     name: 'remove_members',
+    group: 'write',
+    destructive: true,
     description:
       'Remove members from an existing Metro group, in a station-agnostic shape. Args: line ' +
       '(required), members? (string[]). xmtp also accepts addresses?/inboxIds? for backward ' +
@@ -354,6 +370,7 @@ export const COMMON_TOOLS = [
   },
   {
     name: 'export_invite',
+    group: 'write',
     description:
       'Get a join/invite link for a Metro group, for platforms where direct-add is not always ' +
       'permitted. Args: line (required). The station is derived from the line. Returns {op, ' +
@@ -368,8 +385,9 @@ export const COMMON_TOOLS = [
   CREATE_UPLOAD_TOOL,
 ];
 
-export const LIST_ACCOUNTS_TOOL = {
+export const LIST_ACCOUNTS_TOOL: ToolDef = {
   name: 'list_accounts',
+  group: 'read',
   description:
     'List the configured messaging accounts across all stations (PUBLIC identity only: ' +
     'addresses, bot ids/usernames). No args. Never returns tokens, private keys, or the ' +
@@ -378,20 +396,3 @@ export const LIST_ACCOUNTS_TOOL = {
     'verb need not be discovered by trial and error.',
   inputSchema: { type: 'object', properties: {} },
 };
-
-export const MCP_INSTRUCTIONS =
-  'Messages from Metro chat arrive as <channel source="metro" line="..." from="..." ' +
-  'station="..." message_id="...">. To respond, use the messaging tools, always passing the ' +
-  '`line` attribute verbatim (the station is derived from it): `send` (text and/or media via ' +
-  '`attachments`, optional `reply_to`), `reply` (quote a `message_id` with `text`), `react`/' +
-  '`unreact` (emoji on a `message_id`), `edit`/`delete` (a `message_id`), and `read` (recent ' +
-  "history). Station support varies - the tool returns the daemon's reason if a verb is " +
-  'unsupported on that line. An inbound attachment is surfaced as a note carrying the ' +
-  "sender's own text alongside a `Public URL` - fetch that url to read the file; the note's " +
-  '`local_path` resolves on the DAEMON host, not on yours, so the Read tool works on it only ' +
-  'for an agent running there. To send a file OUT, call `create_upload`, ' +
-  'run the one curl line it hands back (that step needs a shell; the bytes go from your disk ' +
-  'straight to metro and never through this conversation), then `send` with ' +
-  'attachments:[{upload:"<upload_id>"}]. Inline `data` is for tiny files only, `url` only for ' +
-  'an already-public file, and `path` is read on the DAEMON host, not yours. Tool-approval ' +
-  'prompts are relayed to the same chat - answer "yes <id>"/"no <id>".';

package/runtime/node_modules/@metro-labs/{mcp → daemon}/src/mcp/upload-tool.ts

@@ -1,34 +1,29 @@
-import { publicBaseOrDefault } from '../daemon/attach-serve.js';
+import { publicBaseOrDefault } from '../files/attach-serve.js';
 import { safeFileName } from '../stations/attach-inline.js';
-import { guessMime } from '../stations/attachments.js';
+import { guessMime } from '@metro-labs/core/stations/attachments';
 import {
   createUploadSlot,
   issueUploadTicket,
   MAX_UPLOAD_BYTES,
   removeUpload,
   UPLOAD_TTL_MS,
-} from '../daemon/upload-store.js';
-import type { ToolResult } from '../stations/types.js';
+} from '../files/upload-store.js';
+import type { ToolResult } from '@metro-labs/core/stations/types';
 import { errResult, okJson } from './ctx.js';
 import { allowedAgents, currentIdentity } from './request-identity.js';
-import { str } from './str.js';
+import { str } from '@metro-labs/core/str';
 
 const ttlMinutes = (): number => Math.round(UPLOAD_TTL_MS / 60_000);
 
 const NO_AGENT =
   'create_upload needs an agent credential; this session is not scoped to one agent';
 
-const manyAgents = (n: number): string =>
-  `create_upload is scoped to one agent, but this session covers ${String(n)}` +
-  ' (a multi-agent sign-in); use `POST /api/uploads?agent=<id>` directly instead';
-
 type OwnerAgent = { agentId: string } | { error: string };
 
 function ownerAgent(): OwnerAgent {
   const allowed = allowedAgents(currentIdentity());
   const [only] = [...allowed];
-  if (allowed.size === 1 && only !== undefined) return { agentId: only };
-  return { error: allowed.size === 0 ? NO_AGENT : manyAgents(allowed.size) };
+  return allowed.size === 1 && only !== undefined ? { agentId: only } : { error: NO_AGENT };
 }
 
 export function dispatchCreateUpload(

package/runtime/node_modules/@metro-labs/daemon/src/metro-user/helper-script.ts

@@ -0,0 +1,183 @@
+const ROOT_DIR = '/usr/local/lib/metro';
+export const HELPER_PATH = `${ROOT_DIR}/root-helper`;
+const HELPER_VERSION = 3;
+export const SUDOERS_PATH = '/etc/sudoers.d/metro';
+export const IMDS_UNIT = 'metro-imds.service';
+export const IMDS_UNIT_PATH = `/etc/systemd/system/${IMDS_UNIT}`;
+export const UPGRADE_UNIT = 'metro-root-upgrade@.service';
+export const UPGRADE_UNIT_PATH = `/etc/systemd/system/${UPGRADE_UNIT}`;
+const RELEASE_DIR = `${ROOT_DIR}/release`;
+export const METRO_USER = 'metro';
+const METRO_HOME = '/var/lib/metro';
+const VAULT_DROP_IN = '11-metro-vault.conf';
+const PRIVILEGED_EXEC = ['ExecConditionEx', 'ExecStartPreEx', 'ExecStartEx', 'ExecStartPostEx', 'ExecReloadEx', 'ExecStopEx', 'ExecStopPostEx'];
+
+export const sudoersText = (agent: string): string =>
+  [
+    `${METRO_USER} ALL=(${agent}) NOPASSWD: ALL`,
+    `${METRO_USER} ALL=(root) NOPASSWD: ${HELPER_PATH} *`,
+    `Defaults:${METRO_USER} !requiretty`,
+    '',
+  ].join('\n');
+
+const lines = (...parts: string[]): string => parts.join('\n');
+
+const CHECKS = lines(
+  'AGENT=agent',
+  'UNITS=/etc/systemd/system',
+  'die() { echo "root-helper: $*" >&2; exit 2; }',
+  'agent_uid() { id -u "$AGENT" 2>/dev/null || die "no agent user"; }',
+  'service_ok() {',
+  '  case "$1" in [!A-Za-z0-9]*|*[!A-Za-z0-9@_.-]*|"") die "bad service name";; esac',
+  '  case "$1" in *.service) ;; *) die "bad service name";; esac',
+  '  case "$1" in metro*) die "not a metro unit";; esac',
+  '  frag=$(systemctl show "$1" -p FragmentPath --value)',
+  '  case "$frag" in "$UNITS"/*) ;; *) die "not a unit under $UNITS";; esac',
+  '  systemctl show "$1" -p TriggeredBy --value | grep -q "\\.timer" || die "not started by a timer"',
+  '}',
+  'agent_only() {',
+  '  [ "$(systemctl show "$1" -p User --value)" = "$AGENT" ] || die "that job does not run as $AGENT"',
+  '  [ "$(systemctl show "$1" -p PermissionsStartOnly --value)" != yes ] || die "that job runs commands as root"',
+  '  [ -n "$(systemctl show "$1" -p ExecStartEx --value)" ] || die "cannot read the commands of that job"',
+  `  if systemctl show "$1" ${PRIVILEGED_EXEC.map((p) => `-p ${p}`).join(' ')} --value | grep -Eq "flags=[^;]*(privileged|no-setuid|ambient)"; then die "that job runs commands as root"; fi`,
+  '}',
+  'dropin_ok() {',
+  `  [ "$1" = ${VAULT_DROP_IN} ] || die "bad drop-in name"`,
+  '  home=$(getent passwd "$AGENT" | cut -d: -f6)',
+  '  printf \'[Service]\\nEnvironmentFile=-%s/.metro/vault.env\\n\' "$home" | cmp -s - "$2" || die "only the vault environment file may be added"',
+  '}',
+);
+
+const FIREWALL = lines(
+  'firewall_on() {',
+  '  uid=$(agent_uid)',
+  '  for t in iptables ip6tables; do',
+  '    $t -w -N METRO_AGENT 2>/dev/null || true',
+  '    $t -w -F METRO_AGENT',
+  '    $t -w -A METRO_AGENT -o lo -j ACCEPT',
+  '    $t -w -A METRO_AGENT -m conntrack --ctstate ESTABLISHED,RELATED -j ACCEPT',
+  '    $t -w -A METRO_AGENT -p udp --dport 53 -j ACCEPT',
+  '    $t -w -A METRO_AGENT -p tcp --dport 53 -j ACCEPT',
+  '    $t -w -A METRO_AGENT -p tcp -j REJECT --reject-with tcp-reset',
+  '    $t -w -A METRO_AGENT -j REJECT',
+  '    $t -w -C OUTPUT -m owner --uid-owner "$uid" -j METRO_AGENT 2>/dev/null || $t -w -I OUTPUT -m owner --uid-owner "$uid" -j METRO_AGENT',
+  '  done',
+  '}',
+  'firewall_off() {',
+  '  uid=$(agent_uid)',
+  '  for t in iptables ip6tables; do',
+  '    while $t -w -C OUTPUT -m owner --uid-owner "$uid" -j METRO_AGENT 2>/dev/null; do $t -w -D OUTPUT -m owner --uid-owner "$uid" -j METRO_AGENT; done',
+  '    $t -w -F METRO_AGENT 2>/dev/null || true',
+  '    $t -w -X METRO_AGENT 2>/dev/null || true',
+  '  done',
+  '}',
+);
+
+const IMDS = lines(
+  'imds_block() {',
+  `  metro_uid=$(id -u ${METRO_USER} 2>/dev/null) || die "no ${METRO_USER} user"`,
+  '  for t in iptables ip6tables; do',
+  '    if [ "$t" = iptables ]; then dst=169.254.169.254; else dst=fd00:ec2::254; fi',
+  '    if ! $t -w -L OUTPUT -n >/dev/null 2>&1; then [ "$t" = ip6tables ] && continue; die "$t is not usable"; fi',
+  '    $t -w -N METRO_IMDS 2>/dev/null || true',
+  '    $t -w -F METRO_IMDS',
+  '    $t -w -A METRO_IMDS -m owner --uid-owner 0 -j RETURN',
+  '    $t -w -A METRO_IMDS -m owner --uid-owner "$metro_uid" -j RETURN',
+  '    $t -w -A METRO_IMDS -p tcp -j REJECT --reject-with tcp-reset',
+  '    $t -w -A METRO_IMDS -j REJECT',
+  '    $t -w -C OUTPUT -d "$dst" -j METRO_IMDS 2>/dev/null || $t -w -I OUTPUT -d "$dst" -j METRO_IMDS',
+  '  done',
+  '}',
+);
+
+export const imdsUnitText = (): string =>
+  lines(
+    '[Unit]',
+    `Description=Metro: only root and ${METRO_USER} reach the instance metadata service`,
+    'DefaultDependencies=no',
+    'After=local-fs.target',
+    'Before=network-pre.target shutdown.target',
+    'Wants=network-pre.target',
+    'Conflicts=shutdown.target',
+    '',
+    '[Service]',
+    'Type=oneshot',
+    'RemainAfterExit=yes',
+    `ExecStart=${HELPER_PATH} imds-block`,
+    '',
+    '[Install]',
+    'WantedBy=multi-user.target',
+    '',
+  );
+
+export const upgradeUnitText = (node: string): string =>
+  lines(
+    '[Unit]',
+    'Description=Metro: bring the root side to Metro %i, checked against npm and its GitHub provenance',
+    'After=network-online.target',
+    'Wants=network-online.target',
+    '',
+    '[Service]',
+    'Type=oneshot',
+    `ExecStart=/usr/bin/flock ${ROOT_DIR} ${node} ${RELEASE_DIR}/dist/cli.js service root-upgrade %i`,
+    'TimeoutStartSec=900',
+    '',
+  );
+
+const ACTIONS = lines(
+  'action="${1:-}"; [ "$#" -gt 0 ] && shift',
+  'case "$action" in',
+  `  version) echo ${String(HELPER_VERSION)} ;;`,
+  '  ensure-agent)',
+  '    getent passwd "$AGENT" >/dev/null || useradd --create-home --shell /bin/bash "$AGENT"',
+  '    chmod 700 "$(getent passwd "$AGENT" | cut -d: -f6)" ;;',
+  '  as-agent-scope)',
+  '    [ "$#" -ge 3 ] || die "usage: as-agent-scope <max> <high> <command...>"',
+  '    printf %s "$1$2" | grep -Eq "^[0-9]+$" || die "bad memory limits"',
+  '    max="$1"; high="$2"; shift 2',
+  '    uid=$(agent_uid); gid=$(id -g "$AGENT")',
+  '    exec systemd-run --scope --quiet --collect --unit="metro-claude-$(date +%s%N)" -p MemoryMax="$max" -p MemoryHigh="$high" -p OOMPolicy=continue -- setpriv --reuid="$uid" --regid="$gid" --init-groups -- "$@" ;;',
+  '  dropin-write)',
+  '    service_ok "$1"; agent_only "$1"; tmp=$(mktemp); trap \'rm -f "$tmp"\' EXIT; head -c 4096 > "$tmp"; dropin_ok "$2" "$tmp"',
+  '    mkdir -p "$UNITS/$1.d"; install -m 644 "$tmp" "$UNITS/$1.d/$2" ;;',
+  '  dropin-remove)',
+  `    service_ok "$1"; [ "$2" = ${VAULT_DROP_IN} ] || die "bad drop-in name"`,
+  '    rm -f "$UNITS/$1.d/$2" ;;',
+  '  daemon-reload) systemctl daemon-reload ;;',
+  '  start-job)',
+  '    service_ok "$1"; [ "$(systemctl show "$1" -p User --value)" = "$AGENT" ] || die "that job does not run as $AGENT"',
+  '    systemctl start --no-block "$1" ;;',
+  '  root-crontab) crontab -l -u root 2>/dev/null || true ;;',
+  '  root-crontab-drop)',
+  '    printf %s "$1" | grep -Eq "^[0-9a-f]{16}$" || die "bad line id"',
+  `    backups="${METRO_HOME}/.metro/agents"`,
+  '    cur=$(mktemp); crontab -l -u root > "$cur" 2>/dev/null || true',
+  '    kept=$(mktemp); found=0',
+  '    while IFS= read -r line; do',
+  '      id=$(printf %s "$line" | sed "s/^[[:space:]]*//;s/[[:space:]]*$//" | tr -d "\\n" | sha256sum | cut -c1-16)',
+  '      if [ "$id" = "$1" ] && [ "$found" = 0 ]; then found=1; elif [ -n "$line" ]; then printf "%s\\n" "$line" >> "$kept"; fi',
+  '    done < "$cur"',
+  '    [ "$found" = 1 ] || die "that cron line is gone"',
+  '    install -m 600 "$cur" "$backups/crontab-root.$(date +%Y-%m-%dT%H-%M-%S).bak"',
+  '    crontab -u root "$kept"; rm -f "$cur" "$kept" ;;',
+  '  imds-block) imds_block ;;',
+  '  upgrade)',
+  '    [ "$#" -eq 1 ] || die "usage: upgrade <version>"',
+  '    case "$1" in *[!0-9A-Za-z.-]*|"") die "bad version";; esac',
+  '    printf %s "$1" | grep -Eqx "[0-9]{1,9}\\.[0-9]{1,9}\\.[0-9]{1,9}(-[0-9A-Za-z]{1,20}(\\.[0-9A-Za-z]{1,20}){0,4})?" || die "bad version"',
+  `    systemctl start --no-block "${UPGRADE_UNIT.replace('@.', '@$1.')}" ;;`,
+  '  firewall-on) firewall_on ;;',
+  '  firewall-off) firewall_off ;;',
+  '  trust-ca)',
+  `    src="${METRO_HOME}/.metro/agents/vault/ca/ca.crt"`,
+  '    head -n1 "$src" | grep -q "BEGIN CERTIFICATE" || die "not a certificate"',
+  '    if grep -q "PRIVATE KEY" "$src"; then die "a key is not a certificate"; fi',
+  '    install -m 644 "$src" /usr/local/share/ca-certificates/metro-vault.crt && update-ca-certificates >/dev/null ;;',
+  '  untrust-ca) rm -f /usr/local/share/ca-certificates/metro-vault.crt; update-ca-certificates --fresh >/dev/null ;;',
+  '  install-nss-tools) DEBIAN_FRONTEND=noninteractive apt-get install -y -q libnss3-tools >/dev/null ;;',
+  '  *) die "unknown action: $action" ;;',
+  'esac',
+);
+
+export const helperScript = (): string =>
+  ['#!/bin/sh', 'set -eu', 'export PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin', CHECKS, FIREWALL, IMDS, ACTIONS, ''].join('\n');

package/runtime/node_modules/@metro-labs/daemon/src/metro-user/imds.ts

@@ -0,0 +1,16 @@
+import { log } from '@metro-labs/core/log';
+import { METRO_VERSION } from '@metro-labs/core/version';
+import { rootHelper, rootStepHint, type HelperResult } from './privilege.js';
+
+export function blockImds(run: (args: string[]) => HelperResult = rootHelper): boolean {
+  const result = run(['imds-block']);
+  if (result.status === 0) {
+    log.info('imds: only root and metro reach the instance metadata service');
+    return true;
+  }
+  log.warn(
+    { err: result.stderr.trim(), fix: rootStepHint(METRO_VERSION) },
+    'imds: the agent can still read the instance metadata (setup data, instance role), since the root helper on this box predates the guard',
+  );
+  return false;
+}