@connexum/ai-governance 1.0.0-beta.21 → 1.0.0-beta.22

package/dist/cli/sync.d.ts

@@ -0,0 +1,189 @@
+/**
+ * ai-governance sync — pull the server's signed governance bundle and
+ * re-materialize the local .governance.json to match.
+ *
+ * Design (Thomas, locked):
+ *   - SAFE BY DEFAULT: no arguments = dry-run. Shows diff, writes nothing.
+ *   - --apply (or interactive confirm) writes the new governance to disk.
+ *   - NOT at runtime, NOT at init — a deliberate standalone verb.
+ *   - Client PULLS from server. Server never calls out to the client (Invariant 10).
+ *   - Server unreachable → graceful message, local config unchanged (Invariant 2/3).
+ *   - Unsigned / tampered bundle → REJECTED, nothing written.
+ *
+ * Usage:
+ *   ai-governance sync                   Dry-run: show diff, no writes
+ *   ai-governance sync --apply           Apply the bundle to .governance.json
+ *   ai-governance sync --agent <id>      Sync a specific agent only
+ *   ai-governance sync --gov-server-url  Override gov server URL
+ *
+ * Source of per-agent identities: .governance.json agents[] written by TS-002
+ * (register-fleet + writePerAgentIdentities). Each entry has:
+ *   { localId, agentId, serviceToken, passportId, filePath }
+ * Plus top-level runtime block:
+ *   { govServerUrl, orgId, agentId, serviceToken }
+ *
+ * Follow-up slices (historic seams — see feat/effective-governance-projection-2026-06-08):
+ *   F1: serviceToken TTL reduced to 30d — DONE
+ *   F2: JTI added to minted tokens, persisted on metadata — DONE
+ *   F3: per-agent audit-logger.sh push rewiring (CXNI_AGENT_FILE resolver) — DONE
+ *   F4: serviceToken moved off curl argv via tmpfile — DONE (this file + audit-logger.sh)
+ *   F5: narrower AGENT_SELF role on server for tighter RBAC — DEFERRED (architectural)
+ *
+ * @connexum/ai-governance  TS-010 sync verb
+ */
+/** Governance section as materialised from the bundle into .governance.json. */
+export interface SyncedGovernance {
+    /** Compliance pack IDs bound by the server. */
+    packs: string[];
+    /** Raw rule overrides from the bundle. */
+    ruleOverrides: unknown[];
+    /** Declared approval gates. */
+    declaredApprovalGates: unknown[];
+    /** Declared forbidden capabilities. */
+    declaredForbiddenCapabilities: string[];
+    /** ISO timestamp the bundle was issued. */
+    bundleIssuedAt: string;
+    /** hex content hash of the bundle payload (for audit). */
+    contentHash: string;
+    /** Ed25519 public key of the org (base64url) that signed this bundle. */
+    signerPublicKeyB64: string;
+}
+/** The shape stored under .governance.json `lastSync` for one agent. */
+export interface AgentLastSync {
+    agentId: string;
+    syncedAt: string;
+    governance: SyncedGovernance;
+}
+/** Per-agent diff result. */
+export interface AgentSyncDiff {
+    agentId: string;
+    filePath?: string;
+    /** null = failed to fetch bundle */
+    bundle: Record<string, unknown> | null;
+    /** null = bundle fetch/verify failed */
+    newGovernance: SyncedGovernance | null;
+    /**
+     * null = no previous sync snapshot (treat as no previous state).
+     * Diff shows "+ <key>: <value>" for all fields on first sync.
+     */
+    previousGovernance: SyncedGovernance | null;
+    diffLines: string[];
+    /** Human-readable error when bundle could not be fetched or verified. */
+    error?: string;
+}
+/** Outcome of runSyncCommand. */
+export interface SyncResult {
+    dryRun: boolean;
+    diffs: AgentSyncDiff[];
+    applied: number;
+    errors: number;
+}
+/** One delivered per-agent token (POST /api/v1/cli/agent-tokens response item). */
+export interface FetchedAgentToken {
+    agentId: string;
+    serviceToken: string;
+    passportId: string | null;
+}
+/**
+ * Fetch the org's Ed25519 public key from the governance server and write it
+ * into .governance.json under `orgPublicKey`.
+ *
+ * SECURITY: this must be called at `ai-governance init` time, BEFORE the first
+ * sync. The key is fetched over authenticated TLS from the same gov-server that
+ * issued the serviceToken. Subsequent syncs verify bundle signatures against
+ * this pinned key — they NEVER trust the key embedded in the bundle itself.
+ *
+ * The endpoint `GET /api/v1/orgs/:orgId/public-key` is unauthenticated (public
+ * keys are public, per Locked Invariant 4). We call it over the same
+ * govServerUrl + orgId that the exchange just returned, giving us a trusted
+ * source: the same TLS channel that authenticated the exchange.
+ *
+ * Returns the pinned key (base64url) on success, or null on failure.
+ * NEVER throws — on failure the caller logs the advisory and continues;
+ * the subsequent sync will fail closed (no pinned key = bundle rejected).
+ *
+ * DEPENDENCY NOTE (2026-06-08 prod incident): the org signing key is currently
+ * in-memory and regenerates on every gov-server deploy. With key-pinning, every
+ * post-deploy sync hits the rotation path until the key is made durable. That
+ * durability fix is the separate incident runbook — this function is still
+ * correct and required (rotation-as-explicit-event is the safe behavior).
+ */
+export declare function fetchAndPinOrgPublicKey(govServerUrl: string, orgId: string, configPath: string, timeoutSec?: number): string | null;
+/**
+ * Verify a governance bundle's Ed25519 signature.
+ *
+ * The signed payload is the JCS-canonical serialization of:
+ *   { agentId, bundleVersion, governance, issuedAt, orgId }
+ * The contentHash is SHA-256(canonical_bytes), hex-encoded.
+ * The signature is Ed25519(raw_sha256_digest_bytes) by the org signing key.
+ *
+ * KEY-TRUST SECURITY (Shield TS-010 remediation):
+ *   `pinnedPublicKeyB64` is the PINNED org public key read from the LOCAL
+ *   .governance.json (written at trusted init time). It is the SOLE key used
+ *   for signature verification. bundle['publicKeyB64'] is NEVER used as the
+ *   verification key — doing so would allow a MITM/rogue server to substitute
+ *   their own key alongside a tampered bundle and have it pass verification.
+ *
+ *   When `pinnedPublicKeyB64` is undefined (no pinned key on disk), the bundle
+ *   is REJECTED (fail closed). Re-running `ai-governance init` pins the key.
+ *
+ *   KEY ROTATION: if bundle['publicKeyB64'] differs from the pinned key, the
+ *   bundle is REJECTED with a rotation message. Key rotation is an EXPLICIT
+ *   operator event — re-run `ai-governance init` to accept the new key over an
+ *   authenticated TLS channel and re-pin it.
+ *
+ * Returns the verified SyncedGovernance on success, or an error string.
+ *
+ * SAFE BY DEFAULT: any failure (missing fields, bad sig, tampered, missing/
+ * mismatched pinned key) returns an error string; the caller MUST NOT apply.
+ */
+export declare function verifyBundle(bundle: Record<string, unknown>, pinnedPublicKeyB64?: string): {
+    ok: true;
+    governance: SyncedGovernance;
+} | {
+    ok: false;
+    error: string;
+};
+/** Produce a human-readable unified-style diff between two SyncedGovernance objects. */
+export declare function computeGovernanceDiff(previous: SyncedGovernance | null, next: SyncedGovernance): string[];
+/**
+ * Apply the synced governance to the local .governance.json.
+ *
+ * Rules:
+ *   1. NEVER silently clobber a hand-edited file. If the local `packs` field
+ *      diverges from what `lastSync[agentId].governance.packs` recorded (i.e.
+ *      the user hand-edited it since the last sync), surface that in the diff
+ *      output. The --apply write still proceeds but the divergence is logged.
+ *   2. Write mode 0o600 — serviceTokens are present in the same file.
+ *   3. The `packs` top-level field is updated only when it is the first sync
+ *      or when --apply is passed. It is the union of all agents' packs.
+ *   4. `lastSync[agentId]` is updated unconditionally on --apply.
+ *
+ * Returns a list of warnings (non-fatal) about hand-edit divergences.
+ */
+export declare function applyGovernanceToLocal(configPath: string, agentId: string, newGovernance: SyncedGovernance): {
+    warnings: string[];
+};
+/**
+ * Parse the args array and run the sync command.
+ *
+ * @param args   Slice of process.argv after 'sync'
+ * @param projectDir  Absolute path to the project directory (default: cwd)
+ * @param options.fetchBundleFn  Override the fetch function for testing
+ * @returns exit code: 0 = success (or dry-run with no errors), 1 = some errors
+ */
+export declare function runSyncCommand(args: string[], projectDir?: string, options?: {
+    /** Injectable fetch function for testing (default: fetchBundle via curl). */
+    fetchBundleFn?: (govServerUrl: string, agentId: string, serviceToken: string) => {
+        bundle: Record<string, unknown> | null;
+        error?: string;
+    };
+    /** Injectable per-agent token fetch for testing (default: fetchAgentTokens via curl). */
+    fetchAgentTokensFn?: (govServerUrl: string, installToken: string) => {
+        tokens: FetchedAgentToken[] | null;
+        error?: string;
+    };
+    /** Suppress all stdout/stderr for testing. */
+    silent?: boolean;
+}): Promise<SyncResult>;
+//# sourceMappingURL=sync.d.ts.map

package/dist/cli/sync.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sync.d.ts","sourceRoot":"","sources":["../../src/cli/sync.ts"],"names":[],"mappings":"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"}