@forgezero/agent 0.1.32 → 0.1.33

package/README.md

@@ -17,14 +17,17 @@ The one public package installs both commands. Keeping bootstrap and the daemon
 in one version prevents a newly installed `fz` from provisioning a different
 agent protocol.
 
-The operator command launches a platform, runs custody ceremonies, inspects
-status, wraps processes, and installs the daemon:
+The operator command starts browser-first platform genesis, inspects status,
+wraps processes, and installs the daemon. Genesis opens the one-use founder
+invitation, waits for the new passkey account to approve this CLI through device
+authorization, then continues custody in the browser. Passkey PRF output and
+both recovery phrases never enter the terminal:
 
 ```bash
 fz keys
 fz status
-fz genesis --mode 2-of-3
-fz unlock
+fz genesis --mode 2-of-3 --api https://api.example --app https://console.example
+fz unlock --phrase-file /secure/offline-phrase.txt # run once per participating custodian
 ```
 
 Install the service explicitly:
@@ -136,6 +139,44 @@ are generated adapters. They contain no independent architecture or progress.
 by hand. Tools and skills remain optional execution aids; accepted decisions and
 status live in the repository and therefore survive switching AI agents.
 
+## Browser-authorized project control
+
+Sign in from any checkout with the public CLI. The terminal displays a device
+code and the browser approves it in the selected tenant realm:
+
+```bash
+fz login --api https://api.forgezero.net --realm acme
+fz whoami
+fz ui routes --json
+```
+
+The short session is stored by API origin and realm in an owner-only local file.
+It is never committed to `.fz/config.json`. A protected mutation opens a browser
+page for passkey or TOTP proof and then replays the exact request once; the CLI
+has no privileged server mode.
+
+Any ordinary website operation is available to developers and AI agents through
+the same API and access matrix:
+
+```bash
+fz ui routes pipeline
+fz ui get /workspace/pipelines --query projectKey=my-project
+fz api post /workspace/pipelines/status \
+  --data '{"pipelineKey":"pl_…","enabled":false}'
+generate-request | fz api post /workspace/action --data -
+```
+
+Only realm-relative paths are accepted, so the saved session cannot be forwarded
+to another origin. Inline JSON, stdin and JSON files are supported. Use
+`fz logout` to revoke the remote session and remove the local copy.
+
+`fz ui routes --json` reads the action catalog from the API's enforced access
+matrix. It lists only the current account's current realm, stage and grants, so
+developers and AI agents can discover the available control surface without a
+copied CLI command list or a visit to the website. Execute any listed action
+with `fz ui <method> <path>`; sensitive actions open the same fresh-proof flow
+as the website and replay the exact request once.
+
 ## Deployment definitions
 
 A repository may commit `.fz/deploy.json` with its own profiles, prerequisite
@@ -155,6 +196,20 @@ fz deploy check
 fz deploy sync
 ```
 
+After sign-in, create and operate the durable pipeline from the same checkout.
+The project defaults to `.fz/config.json`; compute/profile attachments remain
+control-plane state rather than fields in the deploy file:
+
+```bash
+fz deploy connect --provider github --repository acme/web \
+  --clone-url https://github.com/acme/web.git --auth public \
+  --target compute-eu@api --target compute-us@api
+fz deploy list
+fz deploy runs --pipeline <pipeline-key>
+fz deploy release --pipeline <pipeline-key> \
+  --revision <full-40-character-commit> --wait
+```
+
 `init` refuses to invent a generic release or health check: both generated steps
 exit non-zero until the project replaces them. `check` validates the published
 v2 schema and active software coordinates, then prints a formatting-independent
@@ -209,7 +264,7 @@ only claims assigned to its enrolled hostname, then passes
 the fixed claim over a local Unix socket to a narrowly privileged root helper.
 The helper can materialize the audited QEMU profile; it cannot clone a project,
 read Vault data, accept arbitrary commands, or retain tenant credentials. Root
-SSH is an operator-only platform-genesis/recovery path, not the normal tenant
+SSH is an operator-only platform recovery path, not the normal tenant
 dispatch mechanism.
 
 New guests also call this same public `fz agent install --apply --enrol` path

package/dist/agent-heartbeat.d.ts

@@ -1,6 +1,7 @@
 import type { NodeKeyPair } from '@forgezero/runtime/identity';
 import { type AgentRelease } from './agent-update';
 import { type AgentUpdateReceipt, type AgentUpdateResponse } from './agent-update-helper';
+import type { AgentOperationTelemetry } from './telemetry-runtime';
 export interface AgentObservation {
     version: string;
     os: {
@@ -42,6 +43,7 @@ export interface AgentHeartbeatOptions {
     setTimer?: (callback: () => void, ms: number) => unknown;
     clearTimer?: (handle: unknown) => void;
     onEvent?: (event: string, detail?: unknown) => void;
+    telemetry?: AgentOperationTelemetry;
 }
 export declare function observeAgentHost(version?: string, mode?: AgentObservation['mode'], osRelease?: string, architecture?: NodeJS.Architecture): AgentObservation;
 /** One PQ-authenticated observation and optional supervised update decision. */

package/dist/agent-heartbeat.js

@@ -229,6 +229,7 @@ var AGENT_UPDATE_JOURNAL = "/var/lib/forgezero/agent-update.json";
 var AGENT_UPDATE_RECEIPT = "/var/lib/forgezero/agent-update-receipt.json";
 var MAX_REQUEST_BYTES = 8 * 1024;
 var COMPUTE_HELPER_UNITS = [
+  "forgezero-agent-egress.service",
   "forgezero-deploy-runner.service",
   "forgezero-lifecycle-helper.service",
   "forgezero-software-helper.service"
@@ -743,10 +744,14 @@ async function postSignedNode(options, path, body) {
 }
 
 // src/version.ts
-var VERSION3 = "0.1.32";
+var VERSION3 = "0.1.33";
 
 // src/agent-heartbeat.ts
 var unquote = (value) => value.replace(/^['"]|['"]$/g, "");
+var remoteOutcome = (cause) => cause instanceof SignedNodeHttpError && cause.status < 500 ? "refused" : cause instanceof SignedNodeHttpError ? "retryable" : "failed";
+
+class AgentUpdateRefusedError extends Error {
+}
 function observeAgentHost(version = VERSION3, mode = "enrolled", osRelease = readFileSync3("/etc/os-release", "utf8"), architecture = process.arch) {
   const values = Object.fromEntries(osRelease.split(`
 `).flatMap((line) => {
@@ -794,17 +799,25 @@ async function heartbeatAgentOnce(options) {
       try {
         await options.prepareUpdate?.(release);
         prepared = true;
-        const applied = await (options.applyUpdate ?? ((next, current, attemptId) => requestAgentUpdate({
-          op: "apply",
-          target: options.updateTarget ?? "compute",
-          release: next,
-          currentVersion: current,
-          attemptId
-        })))(release, observation.version, desired.attemptId);
-        if (!applied.ok)
-          throw new Error(`agent update refused: ${applied.error.message}`);
-        if (applied.attemptId !== desired.attemptId) {
-          throw new Error("agent update helper returned the wrong rollout attempt");
+        const apply = async () => {
+          const applied = await (options.applyUpdate ?? ((next, current, attemptId) => requestAgentUpdate({
+            op: "apply",
+            target: options.updateTarget ?? "compute",
+            release: next,
+            currentVersion: current,
+            attemptId
+          })))(release, observation.version, desired.attemptId);
+          if (!applied.ok)
+            throw new AgentUpdateRefusedError(`agent update refused: ${applied.error.message}`);
+          if (applied.attemptId !== desired.attemptId) {
+            throw new Error("agent update helper returned the wrong rollout attempt");
+          }
+          return applied;
+        };
+        if (options.telemetry) {
+          await options.telemetry.observe("agent.update", apply, () => "success", (cause) => cause instanceof AgentUpdateRefusedError ? "refused" : "failed");
+        } else {
+          await apply();
         }
         options.onEvent?.("update-staged", { from: observation.version, to: release.version });
       } catch (cause) {
@@ -826,7 +839,8 @@ function startAgentHeartbeat(options) {
     if (stopped || active)
       return;
     let nextSeconds = 30;
-    active = heartbeatAgentOnce(options).then((response) => {
+    const heartbeat = () => heartbeatAgentOnce(options);
+    active = (options.telemetry ? options.telemetry.observe("agent.heartbeat", heartbeat, () => "success", remoteOutcome) : heartbeat()).then((response) => {
       nextSeconds = Math.max(5, Math.min(response.intervalSeconds, 300));
     }).catch((cause) => options.onEvent?.("heartbeat-failed", cause)).finally(() => {
       active = null;

package/dist/agent-update-helper.js

@@ -229,6 +229,7 @@ var AGENT_UPDATE_JOURNAL = "/var/lib/forgezero/agent-update.json";
 var AGENT_UPDATE_RECEIPT = "/var/lib/forgezero/agent-update-receipt.json";
 var MAX_REQUEST_BYTES = 8 * 1024;
 var COMPUTE_HELPER_UNITS = [
+  "forgezero-agent-egress.service",
   "forgezero-deploy-runner.service",
   "forgezero-lifecycle-helper.service",
   "forgezero-software-helper.service"

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>;