@forgezero/agent 0.1.31 → 0.1.33

package/dist/agent-update.js

@@ -2,8 +2,11 @@
 import { createHash, timingSafeEqual, randomUUID } from "node:crypto";
 import {
   chmodSync,
+  closeSync,
   existsSync,
+  fsyncSync,
   mkdirSync,
+  openSync,
   readFileSync,
   readlinkSync,
   renameSync,
@@ -17,6 +20,25 @@ var DEFAULT_AGENT_UPDATE_SOCKET = "/run/forgezero-update/helper.sock";
 var MAX_AGENT_TARBALL_BYTES = 32 * 1024 * 1024;
 var VERSION = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/;
 var REGISTRY = "registry.npmjs.org";
+var syncPath = (path) => {
+  const descriptor = openSync(path, "r");
+  try {
+    fsyncSync(descriptor);
+  } finally {
+    closeSync(descriptor);
+  }
+};
+var syncReleaseDirectory = (directory) => {
+  for (const path of [
+    join(directory, "package.json"),
+    join(directory, "dist", "fz-agent.js"),
+    join(directory, "dist", "fz.js"),
+    join(directory, "dist"),
+    directory,
+    dirname(directory)
+  ])
+    syncPath(path);
+};
 function validateAgentRelease(release) {
   if (release?.package !== "@forgezero/agent")
     throw new Error("agent update package is fixed");
@@ -135,16 +157,24 @@ async function stageAgentRelease(releaseInput, options) {
       ]
     }, "agent update extraction");
     await validateReleaseDirectory(unpacked, release, run);
-    if (!existsSync(finalDirectory))
+    if (!existsSync(finalDirectory)) {
       renameSync(unpacked, finalDirectory);
-    else
+      syncReleaseDirectory(finalDirectory);
+    } else
       await validateReleaseDirectory(finalDirectory, release, run);
     if (!existsSync(currentLink)) {
       throw new Error("agent update requires an active immutable release to roll back to");
     }
     const previousTarget = readlinkSync(currentLink);
+    if (previousTarget !== join("versions", options.currentVersion)) {
+      throw new Error("agent update current release does not match the running version");
+    }
+    if (!existsSync(join(root, previousTarget))) {
+      throw new Error("agent update rollback release is missing");
+    }
     return {
       version: release.version,
+      fromVersion: options.currentVersion,
       directory: finalDirectory,
       previousTarget,
       nextTarget: join("versions", release.version),
@@ -159,6 +189,7 @@ function selectAgentRelease(staged) {
   try {
     symlinkSync(staged.nextTarget, next);
     renameSync(next, staged.currentLink);
+    syncPath(dirname(staged.currentLink));
   } finally {
     rmSync(next, { force: true });
   }
@@ -168,6 +199,7 @@ function restoreAgentRelease(staged) {
   try {
     symlinkSync(staged.previousTarget, next);
     renameSync(next, staged.currentLink);
+    syncPath(dirname(staged.currentLink));
   } finally {
     rmSync(next, { force: true });
   }

package/dist/attestation-client.d.ts

@@ -1,6 +1,7 @@
 import type { NodeKeyPair } from '@forgezero/runtime/identity';
 import type { AttestationSource } from './socket';
 import { type SignedNodeHttpOptions } from './signed-node-http';
+import type { AgentOperationTelemetry } from './telemetry-runtime';
 export interface NodeAttestationOptions extends SignedNodeHttpOptions {
     keys: NodeKeyPair;
     source: AttestationSource;
@@ -10,6 +11,7 @@ export interface NodeAttestationOptions extends SignedNodeHttpOptions {
     setTimer?: (callback: () => void, ms: number) => unknown;
     clearTimer?: (handle: unknown) => void;
     onEvent?: (event: string, detail?: unknown) => void;
+    telemetry?: AgentOperationTelemetry;
 }
 /** One challenge, one PSP report, one signed presentation. */
 export declare function attestNodeOnce(options: NodeAttestationOptions): Promise<{

package/dist/cli/agent-install.d.ts

@@ -16,6 +16,8 @@ import { type Capabilities, type ProvisionPlan } from '../provision';
 export type { ProvisionPlan };
 /** Parse NAME=value pairs used only for non-secret unit coordinates and credential paths. */
 export declare function parseAssignments(value: string | undefined): Record<string, string> | undefined;
+/** Parse an explicit provisioning-owned TCP allowlist; repository data never reaches this input. */
+export declare function parseTcpPorts(value: string | undefined): readonly number[] | undefined;
 /**
  * Answer the capability checks by running their commands.
  *
@@ -50,6 +52,9 @@ export interface InstallOptions {
     deploymentEnvironment?: Record<string, string>;
     deploymentCredentials?: Record<string, string>;
     pullDeployments?: boolean;
+    enforceEgress?: boolean;
+    runnerLoopbackPorts?: readonly number[];
+    runnerPublicTcpPorts?: readonly number[];
     pullMigrations?: boolean;
     lifecycleProfilePath?: string;
     lifecycleHelperSocketPath?: string;
@@ -71,6 +76,7 @@ export interface InstallOptions {
     enrolStatePath?: string;
     nodeLabel?: string;
     nodeHostname?: string;
+    telemetryEndpoint?: string;
 }
 export declare function planInstall(options: InstallOptions): ProvisionPlan;
 /** Execute the same ordered plan the control plane executes over SSH. */

package/dist/cli/genesis.d.ts

@@ -1,19 +1,5 @@
 import { type SealedShare } from '@forgezero/runtime/custody-share';
-import type { UsableIdentity } from './custody';
-/**
- * The genesis ceremony, driven from a terminal.
- *
- * Every value that matters is produced HERE and only sealed material crosses
- * the wire:
- *
- *   phrase   generated locally, printed once, never transmitted or stored
- *   ssh key  derived locally from an agent signature, never transmitted
- *
- * The API receives the derived 32-byte keys because that is what seals a share,
- * and it holds them for exactly the length of one request. Nothing here gives
- * the CLI a privileged path — it calls the same endpoints the browser does, and
- * a bypass that existed for bootstrapping would exist for an attacker too.
- */
+/** Transport shared by the post-genesis vault unlock routine. */
 export interface Transport {
     (path: string, init?: {
         method?: string;
@@ -23,32 +9,6 @@ export interface Transport {
         body: unknown;
     }>;
 }
-export interface GenesisResult {
-    ceremonyKey: string;
-    phrase: string[];
-    fingerprint: string;
-    activated: boolean;
-}
-/**
- * Run a single-custodian genesis.
- *
- * Deliberately limited to the operator running the command. A multi-custodian
- * genesis needs each person at their own terminal with their own agent, which
- * is a coordination problem rather than a code one — and pretending to do it
- * from one shell would mean one machine briefly holding every share.
- */
-export declare function runGenesis(args: {
-    api: Transport;
-    modeId: string;
-    userKey: string;
-    email: string;
-    identity: UsableIdentity;
-    /** The `plt_` token setup.sh wrote. Required — see below. */
-    token: string;
-    displayName?: string;
-    socketPath?: string;
-    onStep?: (message: string) => void;
-}): Promise<GenesisResult>;
 /**
  * Reconstruct the seed and unlock.
  *
@@ -59,9 +19,9 @@ export declare function runGenesis(args: {
 export declare function runUnlock(args: {
     api: Transport;
     userKey: string;
-    identity?: UsableIdentity;
-    phrase?: string[];
-    socketPath?: string;
+    phrase: string[];
+    ceremonyKey: string;
+    fingerprint: string;
     /**
      * This custodian's sealed envelope, read from the ceremony.
      *
@@ -69,11 +29,10 @@ export declare function runUnlock(args: {
      * unlocking. Opening it is a local step now, so no factor travels.
      */
     sealed?: SealedShare;
-    /** The salt the phrase wrapping key was derived over. */
-    phraseSalt?: string;
     onStep?: (message: string) => void;
 }): Promise<{
     fingerprint: string;
+    collected?: number;
+    required?: number;
+    unlocked?: boolean;
 }>;
-/** Resolve `--key` to a usable identity, with an actionable error if it cannot. */
-export declare function resolveIdentity(selector: string | undefined, socketPath?: string): Promise<UsableIdentity>;

package/dist/cli/index.d.ts

@@ -10,3 +10,8 @@ import { type AgentIdentity } from '@forgezero/runtime/ssh-agent';
  */
 export declare function requestHeaders(apiBase: string, cookie: string | null): Record<string, string>;
 export declare function useCustodyIdentity(identity: AgentIdentity, socketPath?: string): void;
+export declare function safeApiPath(value: string): string;
+export declare function targetCoordinate(value: string): {
+    computeReference: string;
+    profile: string;
+};

package/dist/cli/session-store.d.ts

@@ -0,0 +1,22 @@
+/** A short-lived browser-authorized session used only by the public CLI. */
+export interface CliSession {
+    api: string;
+    /** Browser application origin that approved this session and fresh actions. */
+    app?: string;
+    realm: string;
+    cookie: string;
+    createdAtTs: number;
+    lastUsedAtTs: number;
+    user?: {
+        key?: string;
+        email?: string;
+        displayName?: string;
+    };
+}
+export declare function canonicalApi(value: string): string;
+export declare const sessionId: (api: string, realm: string) => string;
+export declare function defaultSessionPath(env?: NodeJS.ProcessEnv): string;
+export declare function activeSession(path?: string): CliSession | null;
+export declare function sessionFor(api: string, realm: string, path?: string): CliSession | null;
+export declare function saveSession(session: CliSession, path?: string): void;
+export declare function removeSession(api: string, realm: string, path?: string): void;

package/dist/deployment-pull.d.ts

@@ -1,5 +1,6 @@
 import type { NodeKeyPair } from '@forgezero/runtime/identity';
 import type { DeploymentManager, DeploymentResult, GitSourceAuth } from './deployment';
+import type { AgentOperationTelemetry } from './telemetry-runtime';
 export interface RemoteDeploymentClaim {
     runKey: string;
     pipelineKey: string;
@@ -36,6 +37,7 @@ export interface DeploymentPullOptions {
     setTimer?: (callback: () => void, ms: number) => unknown;
     clearTimer?: (handle: unknown) => void;
     onEvent?: (event: string, detail?: unknown) => void;
+    telemetry?: AgentOperationTelemetry;
 }
 export type PullResult = {
     status: 'idle';

package/dist/deployment.d.ts

@@ -1,4 +1,5 @@
 import { type DrainReport, type QueueTask } from '@forgezero/runtime/queue';
+import { type GitHostResolver } from './git-egress';
 import type { SoftwareRequirement } from './software';
 import { type RunResult } from './pipeline';
 import type { SecretCache } from './cache';
@@ -58,6 +59,8 @@ export interface DeploymentOptions {
     knownHostsPath?: string;
     /** Server-owned, operator-pinned host keys for a dynamically assigned source. */
     knownHostsContent?: string;
+    /** Test/embedding seam. Production uses the operating system resolver. */
+    resolveGitHost?: GitHostResolver;
     cache?: Pick<SecretCache, 'get'>;
     /** Non-secret values explicitly passed to every project phase. */
     environment?: Record<string, string>;

package/dist/egress-policy.d.ts

@@ -0,0 +1,50 @@
+export declare const AGENT_EGRESS_TABLE = "forgezero_agent_egress";
+export declare const SYSTEMD_RESOLVED_STUB = "/run/systemd/resolve/stub-resolv.conf";
+export declare const SYSTEMD_RESOLVED_ADDRESS = "127.0.0.53";
+export declare const BLOCKED_IPV4: readonly ["0.0.0.0/8", "10.0.0.0/8", "100.64.0.0/10", "127.0.0.0/8", "168.63.129.16/32", "169.254.0.0/16", "172.16.0.0/12", "192.0.0.0/24", "192.0.2.0/24", "192.88.99.0/24", "192.168.0.0/16", "198.18.0.0/15", "198.51.100.0/24", "203.0.113.0/24", "224.0.0.0/4", "240.0.0.0/4"];
+export declare const BLOCKED_IPV6: readonly ["::/128", "::1/128", "::ffff:0:0/96", "64:ff9b::/96", "64:ff9b:1::/48", "100::/64", "fc00::/7", "fec0::/10", "fe80::/10", "ff00::/8", "2001::/32", "2001:2::/48", "2001:10::/28", "2001:20::/28", "2001:db8::/32", "2002::/16", "3fff::/20"];
+export declare const normalizeEgressTcpPorts: (ports: readonly number[]) => readonly number[];
+export interface LoopbackEgressGrant {
+    uid: number;
+    tcpPorts: readonly number[];
+    /** When present, reject every other public protocol/port for this UID. */
+    publicTcpPorts?: readonly number[];
+}
+/** Native cgroup filtering stays active even if an operator later reloads nftables. */
+export declare function systemdAgentEgressDirectives(loopbackTcpPorts?: readonly number[]): string;
+/** One atomic nftables transaction installed before systemd marks the policy ready. */
+export declare function renderAgentEgressNft(uids: readonly number[], replace?: boolean, loopback?: LoopbackEgressGrant): string;
+export interface EgressCommandResult {
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+}
+export type EgressCommand = (argv: readonly string[], stdin?: string) => EgressCommandResult;
+export declare function resolveServiceUid(user: string, command?: EgressCommand): number;
+export declare function assertResolvedStub(realpath?: (path: string) => string): void;
+export declare function verifyAgentEgressPolicy(uids: readonly number[], command?: EgressCommand, loopback?: LoopbackEgressGrant): boolean;
+export declare function applyAgentEgressPolicy(options: {
+    users: readonly string[];
+    loopback?: {
+        user: string;
+        tcpPorts: readonly number[];
+        publicTcpPorts?: readonly number[];
+    };
+    command?: EgressCommand;
+    realpath?: (path: string) => string;
+    getuid?: () => number;
+}): readonly number[];
+export declare function superviseAgentEgressPolicy(options: {
+    users: readonly string[];
+    loopback?: {
+        user: string;
+        tcpPorts: readonly number[];
+        publicTcpPorts?: readonly number[];
+    };
+    command?: EgressCommand;
+    realpath?: (path: string) => string;
+    getuid?: () => number;
+    intervalMs?: number;
+    notifyReady?: () => void;
+    wait?: (milliseconds: number) => Promise<void>;
+}): Promise<never>;