@lamalibre/create-lamaste 4.2.0 → 4.3.0

package/vendor/serverd/src/lib/plugins.js

@@ -11,22 +11,28 @@
 import { readFile, writeFile, mkdir, rm } from 'node:fs/promises';
 import { createRequire } from 'node:module';
 import path from 'node:path';
-import { z } from 'zod';
 import { execa } from 'execa';
 import {
   DEFAULT_PLUGIN_HOSTING,
+  ManifestValidationError,
   RESERVED_API_PREFIXES,
   RESERVED_NAV_LABELS,
   derivePluginRoute,
+  hasAgentHalf,
+  pluginHostCapability,
   validateManifest as coreValidateManifest,
 } from '@lamalibre/lamaste';
-import { revokePluginCapabilitiesFromAgents } from '@lamalibre/lamaste/server';
 import { listRegisteredSubScopeNames } from './tickets.js';
 import { getStateDb } from './state-db.js';
+import { revokePluginCapabilitiesFromAgents } from './mtls.js';
+import {
+  bareLamalibrePackageName,
+  installedHookEntrySha256,
+  pinAgentHalf,
+} from './plugin-packages.js';
 
 const STATE_DIR = process.env.LAMALIBRE_LAMASTE_STATE_DIR || '/etc/lamalibre/lamaste';
 const PLUGINS_DIR = path.join(STATE_DIR, 'plugins');
-const PKI_DIR = process.env.LAMALIBRE_LAMASTE_PKI_DIR || '/etc/lamalibre/lamaste/pki';
 
 // Promise-chain mutex. SQLite's BEGIN IMMEDIATE serialises a single write
 // transaction, but install/uninstall are read-modify-write sequences that
@@ -57,12 +63,14 @@ async function getStmts() {
 
     selectAll: db.prepare('SELECT * FROM plugins'),
     selectByName: db.prepare('SELECT * FROM plugins WHERE name = ?'),
+    selectByRoute: db.prepare('SELECT * FROM plugins WHERE route = ?'),
     selectByPackageName: db.prepare('SELECT * FROM plugins WHERE package_name = ?'),
     insert: db.prepare(`
       INSERT INTO plugins
-        (name, display_name, package_name, version, description, capabilities,
-         packages, panel, config, modes, hosting, status, installed_at, enabled_at)
-      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+        (name, route, display_name, package_name, version, description, capabilities,
+         packages, panel, config, modes, hosting, agent, hooks, hooks_entry_sha256,
+         agent_half_pin, status, installed_at, enabled_at)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
     `),
     deleteByName: db.prepare('DELETE FROM plugins WHERE name = ?'),
     deleteAll: db.prepare('DELETE FROM plugins'),
@@ -90,11 +98,16 @@ async function getStmts() {
 // missing keys are absent rather than null). `hosting` is plain TEXT
 // ('server' | 'agent'; rows from before 4.2 default to 'server'): an
 // agent-hosted plugin is installed (npm, manifest) like any other, but the
-// plugin host never imports it — see `pluginHostPlugin`.
+// plugin host never imports it — see `pluginHostPlugin`. `route` is the
+// plugin's route (`derivePluginRoute(name)`), unique among installed
+// plugins; null only for a plugin installed before routes were unique that
+// shares its route with an older one (migration 0010) — such a plugin is
+// never hosted and its uninstall leaves the route's capabilities alone.
 
 function rowToPlugin(row) {
   const entry = {
     name: row.name,
+    route: row.route ?? null,
     packageName: row.package_name,
     version: row.version,
     capabilities: row.capabilities ? JSON.parse(row.capabilities) : [],
@@ -108,6 +121,10 @@ function rowToPlugin(row) {
   if (row.panel != null) entry.panel = JSON.parse(row.panel);
   if (row.config != null) entry.config = JSON.parse(row.config);
   if (row.modes != null) entry.modes = JSON.parse(row.modes);
+  if (row.agent != null) entry.agent = JSON.parse(row.agent);
+  if (row.hooks != null) entry.hooks = JSON.parse(row.hooks);
+  if (row.hooks_entry_sha256 != null) entry.hooksEntrySha256 = row.hooks_entry_sha256;
+  if (row.agent_half_pin != null) entry.agentHalfPin = JSON.parse(row.agent_half_pin);
   if (row.enabled_at != null) entry.enabledAt = row.enabled_at;
   return entry;
 }
@@ -151,6 +168,7 @@ export async function writePlugins(data) {
     for (const p of list) {
       s.insert.run(
         p.name,
+        p.route === undefined ? derivePluginRoute(p.name) : p.route,
         nullableString(p.displayName),
         p.packageName,
         p.version,
@@ -161,6 +179,10 @@ export async function writePlugins(data) {
         nullableJson(p.config),
         nullableJson(p.modes),
         p.hosting ?? DEFAULT_PLUGIN_HOSTING,
+        nullableJson(p.agent),
+        nullableJson(p.hooks),
+        nullableString(p.hooksEntrySha256),
+        nullableJson(p.agentHalfPin),
         p.status,
         p.installedAt,
         nullableString(p.enabledAt),
@@ -179,7 +201,7 @@ export async function writePlugins(data) {
  *
  * @param {object} raw - The raw manifest object
  * @returns {object} The validated and parsed manifest
- * @throws {z.ZodError} If validation fails
+ * @throws {ManifestValidationError} If validation fails
  */
 export function validateManifest(raw) {
   return coreValidateManifest(raw);
@@ -236,10 +258,74 @@ async function syncOidcClientsBestEffort(logger) {
   }
 }
 
+/**
+ * The panel's rules for a manifest beyond its schema — checked at install
+ * and again for an update. Returns `{ message, statusCode }` or null.
+ */
+export async function manifestPolicyError(manifest) {
+  // Names that collide with core API route prefixes
+  if (RESERVED_API_PREFIXES.includes(manifest.name)) {
+    return { message: `Plugin name "${manifest.name}" is reserved`, statusCode: 400 };
+  }
+  // A displayName that matches a core navigation label
+  if (manifest.displayName && RESERVED_NAV_LABELS.includes(manifest.displayName.toLowerCase())) {
+    return {
+      message: `Plugin display name "${manifest.displayName}" conflicts with a core navigation label`,
+      statusCode: 400,
+    };
+  }
+  // A plugin with an agent half is named by its route: the route keys its
+  // hosting, its internal tunnel, its agent half's account and directories
+  // on the agent and its forwarded API (`/api/<route>`), while its hook
+  // state, operations and audit entries go by name — the two must be one.
+  if (hasAgentHalf(manifest)) {
+    const route = derivePluginRoute(manifest.name);
+    if (route !== manifest.name) {
+      return {
+        message: `A plugin with an agent half is named by its route: "${manifest.name}" would be served as "${route}" — name it "${route}" (its packages keep their names)`,
+        statusCode: 400,
+      };
+    }
+  }
+  // apiPrefix must match the plugin name
+  if (manifest.panel?.apiPrefix && manifest.panel.apiPrefix !== `/api/${manifest.name}`) {
+    return {
+      message: `Plugin apiPrefix must be "/api/${manifest.name}" but got "${manifest.panel.apiPrefix}"`,
+      statusCode: 400,
+    };
+  }
+  // Cross-namespace collision: any capability declared by the plugin must
+  // not match a sub-scope name already owned by a registered ticket scope.
+  // Schema-level namespacing puts both sides in `plugin:*`; this check is
+  // a flat set intersection. The reverse direction (registering a scope
+  // that collides with an installed plugin's cap) is enforced in
+  // `registerScope`.
+  if (Array.isArray(manifest.capabilities) && manifest.capabilities.length > 0) {
+    const subScopeNames = new Set(await listRegisteredSubScopeNames());
+    const collision = manifest.capabilities.find((c) => subScopeNames.has(c));
+    if (collision) {
+      return {
+        message:
+          `Plugin capability "${collision}" collides with an existing ticket scope sub-scope name. ` +
+          'Pick a different action name or unregister the conflicting ticket scope first.',
+        statusCode: 409,
+      };
+    }
+  }
+  return null;
+}
+
 export function installPlugin(packageName, logger) {
   return withPluginLock(async () => {
     // Validate package scope
     assertSafeLamalibrePackage(packageName);
+    // `@lamalibre/x@1.2.3` installs that version; the registry knows the
+    // package by its bare name (the manifest is resolved by it, too).
+    const installSpec = packageName;
+    packageName = bareLamalibrePackageName(installSpec);
+    // Remove the package npm installed when it is refused below.
+    const discardPackage = () =>
+      execa('npm', ['uninstall', packageName], { cwd: STATE_DIR }).catch(() => {});
 
     const s = await getStmts();
 
@@ -262,15 +348,18 @@ export function installPlugin(packageName, logger) {
     }
 
     // Install the npm package
-    logger.info({ packageName }, 'Installing plugin package');
+    logger.info({ packageName: installSpec }, 'Installing plugin package');
     try {
-      await execa('npm', ['install', '--ignore-scripts', packageName], {
+      await execa('npm', ['install', '--ignore-scripts', installSpec], {
         cwd: STATE_DIR,
         timeout: 120000,
       });
     } catch (err) {
-      logger.error({ packageName, stderr: err.stderr, err: err.message }, 'npm install failed');
-      throw Object.assign(new Error(`Failed to install "${packageName}"`), { statusCode: 500 });
+      logger.error(
+        { packageName: installSpec, stderr: err.stderr, err: err.message },
+        'npm install failed',
+      );
+      throw Object.assign(new Error(`Failed to install "${installSpec}"`), { statusCode: 500 });
     }
 
     // Read the plugin manifest from the installed package
@@ -283,70 +372,58 @@ export function installPlugin(packageName, logger) {
     } catch (err) {
       // Clean up the installed package if manifest is missing/invalid
       logger.warn({ packageName, err: err.message }, 'Invalid or missing manifest, uninstalling');
-      await execa('npm', ['uninstall', packageName], { cwd: STATE_DIR }).catch(() => {});
+      await discardPackage();
 
-      if (err instanceof z.ZodError) {
-        throw Object.assign(
-          new Error(`Invalid plugin manifest: ${err.errors.map((e) => e.message).join(', ')}`),
-          { statusCode: 400 },
-        );
+      if (err instanceof ManifestValidationError) {
+        throw Object.assign(new Error(err.message), { statusCode: 400 });
       }
       throw Object.assign(new Error(`Plugin manifest not found in "${packageName}"`), {
         statusCode: 400,
       });
     }
 
-    // Reject names that collide with core API route prefixes
-    if (RESERVED_API_PREFIXES.includes(manifest.name)) {
-      await execa('npm', ['uninstall', packageName], { cwd: STATE_DIR }).catch(() => {});
-      throw Object.assign(new Error(`Plugin name "${manifest.name}" is reserved`), {
-        statusCode: 400,
-      });
+    const policyError = await manifestPolicyError(manifest);
+    if (policyError) {
+      await discardPackage();
+      throw Object.assign(new Error(policyError.message), { statusCode: policyError.statusCode });
     }
 
-    // Reject displayName that matches reserved navigation labels
-    if (manifest.displayName) {
-      if (RESERVED_NAV_LABELS.includes(manifest.displayName.toLowerCase())) {
-        await execa('npm', ['uninstall', packageName], { cwd: STATE_DIR }).catch(() => {});
-        throw Object.assign(
-          new Error(
-            `Plugin display name "${manifest.displayName}" conflicts with a core navigation label`,
-          ),
-          { statusCode: 400 },
-        );
-      }
+    // A plugin with relay hooks of its own: its module must be in the
+    // package; its SHA-256 goes into the hook set's digest, which an admin
+    // approves before Lamaste runs it.
+    let hooksEntrySha256 = null;
+    try {
+      hooksEntrySha256 = await installedHookEntrySha256(packageName, manifest);
+    } catch (err) {
+      await discardPackage();
+      throw Object.assign(new Error(err.message), { statusCode: err.statusCode || 400 });
     }
 
-    // Validate apiPrefix matches plugin name if specified
-    if (manifest.panel?.apiPrefix && manifest.panel.apiPrefix !== `/api/${manifest.name}`) {
-      await execa('npm', ['uninstall', packageName], { cwd: STATE_DIR }).catch(() => {});
-      throw Object.assign(
-        new Error(
-          `Plugin apiPrefix must be "/api/${manifest.name}" but got "${manifest.panel.apiPrefix}"`,
-        ),
-        { statusCode: 400 },
-      );
+    // An agent half Lamaste installs: its tarball's integrity is pinned now,
+    // from the registry this install used — the approval covers it and the
+    // agent installs only a tarball that matches it.
+    let agentHalfPin = null;
+    try {
+      agentHalfPin = await pinAgentHalf(manifest);
+    } catch (err) {
+      await discardPackage();
+      throw Object.assign(new Error(err.message), { statusCode: err.statusCode || 400 });
     }
 
-    // Cross-namespace collision: any capability declared by the plugin must
-    // not match a sub-scope name already owned by a registered ticket scope.
-    // Schema-level namespacing puts both sides in `plugin:*`; this check is
-    // a flat set intersection. The reverse direction (registering a scope
-    // that collides with an installed plugin's cap) is enforced in
-    // `registerScope`.
-    if (Array.isArray(manifest.capabilities) && manifest.capabilities.length > 0) {
-      const subScopeNames = new Set(await listRegisteredSubScopeNames());
-      const collision = manifest.capabilities.find((c) => subScopeNames.has(c));
-      if (collision) {
-        await execa('npm', ['uninstall', packageName], { cwd: STATE_DIR }).catch(() => {});
-        throw Object.assign(
-          new Error(
-            `Plugin capability "${collision}" collides with an existing ticket scope sub-scope name. ` +
-              'Pick a different action name or unregister the conflicting ticket scope first.',
-          ),
-          { statusCode: 409 },
-        );
-      }
+    // A name another installed package already uses would fail the INSERT
+    // below and leave this package behind.
+    if (s.selectByName.get(manifest.name)) {
+      await discardPackage();
+      throw Object.assign(new Error(`A plugin named "${manifest.name}" is already installed`), {
+        statusCode: 409,
+      });
+    }
+    // So would its route (unique index): one installed plugin per route.
+    const route = derivePluginRoute(manifest.name);
+    const routeOwner = s.selectByRoute.get(route);
+    if (routeOwner) {
+      await discardPackage();
+      throw routeTakenError(manifest.name, route, routeOwner.name);
     }
 
     // Create the plugin state directory
@@ -356,6 +433,7 @@ export function installPlugin(packageName, logger) {
     // Build the entry, then persist via INSERT
     const entry = {
       name: manifest.name,
+      route,
       displayName: manifest.displayName,
       packageName,
       version: manifest.version,
@@ -366,6 +444,10 @@ export function installPlugin(packageName, logger) {
       config: manifest.config,
       modes: manifest.modes,
       hosting: manifest.hosting,
+      agent: manifest.agent,
+      hooks: manifest.hooks,
+      hooksEntrySha256,
+      agentHalfPin,
       status: 'disabled',
       installedAt: new Date().toISOString(),
     };
@@ -374,6 +456,7 @@ export function installPlugin(packageName, logger) {
     try {
       s.insert.run(
         entry.name,
+        entry.route,
         nullableString(entry.displayName),
         entry.packageName,
         entry.version,
@@ -384,6 +467,10 @@ export function installPlugin(packageName, logger) {
         nullableJson(entry.config),
         nullableJson(entry.modes),
         entry.hosting,
+        nullableJson(entry.agent),
+        nullableJson(entry.hooks),
+        nullableString(entry.hooksEntrySha256),
+        nullableJson(entry.agentHalfPin),
         entry.status,
         entry.installedAt,
         null,
@@ -424,6 +511,24 @@ export function uninstallPlugin(name, logger) {
       });
     }
 
+    // A hosted plugin is uninstalled by an operation that runs its
+    // uninstall pipeline first (plugin-lifecycle.js); by the time it gets
+    // here the hosting is gone.
+    if (hasAgentHalf(plugin)) {
+      const { isPluginHosted } = await import('./plugin-hosting.js');
+      if (await isPluginHosted(name)) {
+        throw Object.assign(
+          new Error(`Plugin "${name}" is hosted on an agent — its hosting is removed first`),
+          { statusCode: 409 },
+        );
+      }
+    }
+
+    // Its relay hook runner and approval go with it: a later install of the
+    // plugin is approved afresh.
+    const { removeRelayHooks } = await import('./plugin-hooks.js');
+    await removeRelayHooks(name, logger);
+
     // Uninstall the npm package
     logger.info({ name, packageName: plugin.packageName }, 'Uninstalling plugin package');
     await execa('npm', ['uninstall', plugin.packageName], {
@@ -450,12 +555,24 @@ export function uninstallPlugin(name, logger) {
 
     // Sweep this plugin's capabilities off every agent so re-installing the
     // plugin later does NOT silently re-grant. Failure here is non-fatal
-    // (the plugin is already gone), but logged loudly.
+    // (the plugin is already gone), but logged loudly. A plugin without a
+    // route of its own shares its namespace with the plugin that holds the
+    // route: the capabilities are that plugin's, and stay.
     try {
-      const route = derivePluginRoute(plugin.name);
-      const diffs = await revokePluginCapabilitiesFromAgents(PKI_DIR, route);
-      if (diffs.length > 0) {
-        logger.info({ name, route, diffs }, 'Revoked plugin capabilities from agents on uninstall');
+      const route = plugin.route;
+      if (route === null) {
+        logger.warn(
+          { name, route: derivePluginRoute(plugin.name) },
+          'Plugin shares its route with another installed plugin — its capabilities are left in place',
+        );
+      } else {
+        const diffs = await revokePluginCapabilitiesFromAgents(route);
+        if (diffs.length > 0) {
+          logger.info(
+            { name, route, diffs },
+            'Revoked plugin capabilities from agents on uninstall',
+          );
+        }
       }
     } catch (err) {
       logger.warn(
@@ -470,6 +587,83 @@ export function uninstallPlugin(name, logger) {
   });
 }
 
+// --- In-place update (agent-hosted plugins) ---
+
+const updateRowSql = `
+  UPDATE plugins SET
+    display_name = ?, version = ?, description = ?, capabilities = ?, packages = ?, panel = ?,
+    config = ?, modes = ?, hosting = ?, agent = ?, hooks = ?, hooks_entry_sha256 = ?,
+    agent_half_pin = ?
+  WHERE name = ?`;
+
+/**
+ * Rewrite an installed plugin's row from a manifest (an update, or its
+ * reversal) with the agent half pinned for that version (null when Lamaste
+ * installs none). Status and install time stay.
+ */
+export async function writePluginRow(name, manifest, hooksEntrySha256, agentHalfPin) {
+  const s = await getStmts();
+  s.db
+    .prepare(updateRowSql)
+    .run(
+      nullableString(manifest.displayName),
+      manifest.version,
+      nullableString(manifest.description),
+      JSON.stringify(manifest.capabilities ?? []),
+      nullableJson(manifest.packages),
+      nullableJson(manifest.panel),
+      nullableJson(manifest.config),
+      nullableJson(manifest.modes),
+      manifest.hosting ?? DEFAULT_PLUGIN_HOSTING,
+      nullableJson(manifest.agent),
+      nullableJson(manifest.hooks),
+      nullableString(hooksEntrySha256),
+      nullableJson(agentHalfPin),
+      name,
+    );
+}
+
+/**
+ * Install `<packageName>@<version>` over the installed copy and read it
+ * back: the validated manifest and its relay entry module's SHA-256. The
+ * row is not touched — the caller compares the result with what was
+ * reviewed and then writes it. Refuses a package whose manifest names
+ * another plugin.
+ */
+export function replacePluginPackage(name, packageName, version, logger) {
+  return withPluginLock(async () => {
+    const bare = bareLamalibrePackageName(packageName);
+    const spec = `${bare}@${version}`;
+    assertSafeLamalibrePackage(spec);
+    logger?.info({ name, spec }, 'Installing plugin package version');
+    try {
+      await execa('npm', ['install', '--ignore-scripts', spec], {
+        cwd: STATE_DIR,
+        timeout: 120000,
+      });
+    } catch (err) {
+      logger?.error({ spec, stderr: err.stderr, err: err.message }, 'npm install failed');
+      throw Object.assign(new Error(`Failed to install "${spec}"`), { statusCode: 502 });
+    }
+    const require = createRequire(`${STATE_DIR}/`);
+    const manifestPath = require.resolve(`${bare}/lamaste-plugin.json`);
+    const manifest = validateManifest(JSON.parse(await readFile(manifestPath, 'utf-8')));
+    if (manifest.name !== name) {
+      throw Object.assign(new Error(`${spec} is plugin "${manifest.name}", not "${name}"`), {
+        statusCode: 400,
+      });
+    }
+    if (manifest.version !== version) {
+      throw Object.assign(
+        new Error(`${spec} installed version ${manifest.version} according to its manifest`),
+        { statusCode: 400 },
+      );
+    }
+    const hooksEntrySha256 = await installedHookEntrySha256(packageName, manifest);
+    return { manifest, hooksEntrySha256 };
+  });
+}
+
 /**
  * Enable a plugin.
  *
@@ -565,6 +759,42 @@ export async function getPluginCapabilities() {
       const parsed = JSON.parse(row.capabilities);
       if (Array.isArray(parsed)) caps.push(...parsed);
     }
+    // `plugin:<route>:host` is never declared: Lamaste contributes it for
+    // every installed agent-hosted plugin with an agent half, enabled or
+    // not — hosting is an administrator's binding and outlives a disable.
+    if (row.hosting === 'agent' && row.agent != null && row.route != null) {
+      caps.push(pluginHostCapability(row.route));
+    }
   }
   return [...new Set(caps)];
 }
+
+/**
+ * One installed plugin by name, or null.
+ * @param {string} name
+ */
+export async function findPlugin(name) {
+  const s = await getStmts();
+  const row = s.selectByName.get(name);
+  return row ? rowToPlugin(row) : null;
+}
+
+/**
+ * The installed plugin that holds route `route`, or null.
+ * @param {string} route
+ */
+export async function findPluginByRoute(route) {
+  const s = await getStmts();
+  const row = s.selectByRoute.get(route);
+  return row ? rowToPlugin(row) : null;
+}
+
+/** 409 `route_taken`: another installed plugin holds the route. */
+function routeTakenError(name, route, owner) {
+  return Object.assign(
+    new Error(
+      `Plugin "${name}" would use route "${route}", which installed plugin "${owner}" holds — a route (the name without "-server" or "-agent") names one plugin's API, capabilities, hosting and agent half`,
+    ),
+    { statusCode: 409, code: 'route_taken', route, owner },
+  );
+}

package/vendor/serverd/src/lib/push-install.js

@@ -23,6 +23,16 @@ function pushInstallConfigPath() {
   return path.join(STATE_DIR, 'push-install-config.json');
 }
 
+/** Actions a push-install policy can allow. */
+export const PUSH_INSTALL_ACTIONS = ['install', 'update', 'uninstall', 'check-prerequisites'];
+
+/**
+ * How long an agent's push-install window may be opened for, in minutes —
+ * enforced when one is opened and reported with the config, so clients
+ * offer the same bounds.
+ */
+export const PUSH_INSTALL_WINDOW_MINUTES = Object.freeze({ min: 5, max: 480 });
+
 const DEFAULT_POLICY = {
   id: 'default',
   name: 'Default',
@@ -30,9 +40,33 @@ const DEFAULT_POLICY = {
   allowedIps: [],
   deniedIps: [],
   allowedPlugins: [],
-  allowedActions: ['install', 'update', 'check-prerequisites'],
+  allowedActions: ['install', 'update', 'uninstall', 'check-prerequisites'],
 };
 
+/**
+ * The default policy's actions before `uninstall` joined them (4.3: removing
+ * an agent half Lamaste installed is a push to the agent too).
+ */
+const DEFAULT_ACTIONS_BEFORE_UNINSTALL = ['install', 'update', 'check-prerequisites'];
+
+/**
+ * A stored default policy whose actions were never edited gets `uninstall`
+ * with the default it was written from — the administrator chose nothing
+ * that excludes it. A policy that was edited, or any other policy, stays
+ * as stored.
+ */
+function withCurrentDefaults(policy) {
+  if (
+    policy?.id === DEFAULT_POLICY.id &&
+    Array.isArray(policy.allowedActions) &&
+    policy.allowedActions.length === DEFAULT_ACTIONS_BEFORE_UNINSTALL.length &&
+    DEFAULT_ACTIONS_BEFORE_UNINSTALL.every((a, i) => policy.allowedActions[i] === a)
+  ) {
+    return { ...policy, allowedActions: [...DEFAULT_POLICY.allowedActions] };
+  }
+  return policy;
+}
+
 const DEFAULT_PUSH_INSTALL_CONFIG = {
   enabled: false,
   policies: [structuredClone(DEFAULT_POLICY)],
@@ -51,7 +85,7 @@ export async function readPushInstallConfig() {
     return {
       enabled: parsed.enabled ?? false,
       policies: Array.isArray(parsed.policies)
-        ? parsed.policies
+        ? parsed.policies.map(withCurrentDefaults)
         : [structuredClone(DEFAULT_POLICY)],
       defaultPolicy: parsed.defaultPolicy || 'default',
     };
@@ -388,3 +422,55 @@ export async function validatePushInstallAccess(label, sourceIp) {
 
   return { ok: true, agent, config, policy };
 }
+
+/**
+ * Whether `policy` allows `action` on `packageName`. An empty list allows
+ * everything (as the policy editor documents). Returns the refusal, or null.
+ *
+ * @param {{ allowedActions?: string[], allowedPlugins?: string[] }} policy
+ * @param {string} action
+ * @param {string | null} packageName
+ * @returns {{ error: string, statusCode: number } | null}
+ */
+export function pushInstallPolicyRefusal(policy, action, packageName) {
+  if (
+    Array.isArray(policy.allowedActions) &&
+    policy.allowedActions.length > 0 &&
+    !policy.allowedActions.includes(action)
+  ) {
+    return { error: `Action "${action}" is not allowed by the assigned policy`, statusCode: 403 };
+  }
+  if (
+    packageName &&
+    Array.isArray(policy.allowedPlugins) &&
+    policy.allowedPlugins.length > 0 &&
+    !policy.allowedPlugins.includes(packageName)
+  ) {
+    return {
+      error: `Package "${packageName}" is not allowed by the assigned policy`,
+      statusCode: 403,
+    };
+  }
+  return null;
+}
+
+/**
+ * The push-install gates for one push to agent `label` from `sourceIp`:
+ * {@link validatePushInstallAccess} (global switch, the agent's window,
+ * the source IP) and the assigned policy's actions and packages. Hosting,
+ * updating and removing an agent half Lamaste installs are pushes: the
+ * relay has the agent install, switch or remove code as root.
+ *
+ * @param {string} label
+ * @param {string} sourceIp
+ * @param {'install' | 'update' | 'uninstall'} action
+ * @param {string} packageName the agent half's package
+ * @returns {Promise<{ ok: true, policy: object } | { ok: false, error: string, statusCode: number }>}
+ */
+export async function checkPushInstallAction(label, sourceIp, action, packageName) {
+  const access = await validatePushInstallAccess(label, sourceIp);
+  if (!access.ok) return access;
+  const refusal = pushInstallPolicyRefusal(access.policy, action, packageName);
+  if (refusal) return { ok: false, ...refusal };
+  return { ok: true, policy: access.policy };
+}