@phnx-labs/agents-cli 1.22.84 → 1.22.85

package/dist/lib/secrets-policy.d.ts

@@ -0,0 +1,222 @@
+import { type SecretsContext } from './secrets-client.js';
+import type { PushBundleResult } from './secrets-types.js';
+import type { AgentId, Meta, NativeAccountRecord } from './types.js';
+import { type DeviceProfile } from './devices/registry.js';
+import { type SharedAuthStatus } from './fleet-shared-state.js';
+import { selfConfiguredDeviceRole } from './device-config.js';
+import { AUTH_STORE_ALIAS, AUTH_BUNDLE_NAME, AUTH_BUNDLE_BACKEND, RESERVED_BUNDLE_NAMES, isReservedBundleName, ReservedBundleWrongBackendError, assertReservedAuthBackend, isReservedBundleBackendError, RESERVED_STORES, reservedStoreName, isReservedStoreName, assertStorableCredentialKind, inspectReservedAuthBundle, type StorableCredentialKind } from './reserved-stores.js';
+export { AUTH_STORE_ALIAS, AUTH_BUNDLE_NAME, AUTH_BUNDLE_BACKEND, RESERVED_BUNDLE_NAMES, isReservedBundleName, ReservedBundleWrongBackendError, assertReservedAuthBackend, isReservedBundleBackendError, RESERVED_STORES, reservedStoreName, isReservedStoreName, assertStorableCredentialKind, inspectReservedAuthBundle, type StorableCredentialKind, };
+/** Filter `names` down to the ones the active resource profile allows for `secrets`. */
+export declare function filterBundleNamesForActiveProfile(names: string[]): string[];
+/**
+ * `SecretsContext.allowedBundles` for the active resource profile, or
+ * `undefined` when no profile is active (full trust — the client's default).
+ * `allNames` is the caller's already-fetched full bundle listing (e.g. from
+ * `listBundlesSync()`), so this stays a pure filter with no extra round trip.
+ */
+export declare function resolveAllowedBundlesForActiveProfile(allNames: string[]): string[] | undefined;
+/**
+ * The `SecretsContext` a run should pass to every bundle resolution it makes:
+ * the run's harness as the opaque `scope`, plus `allowedBundles` computed from
+ * a fresh full bundle listing when a resource profile is active (a stale
+ * listing could exclude a bundle created after the profile was set). No
+ * profile active means full trust and no extra round trip.
+ */
+export declare function resolveSecretsContextForRun(scope?: string): Promise<SecretsContext | undefined>;
+/** Parse a `--secrets` flag value into its bundle name and optional `@host`. */
+export declare function splitBundleRef(ref: string): {
+    bundle: string;
+    host?: string;
+};
+/** A remote (bundle@host) reference does not yet support key-subset or expiry overrides. */
+export declare function assertRemoteBundleFlagsUnsupported(bundleName: string, host: string, opts: {
+    keys?: string[];
+    allowExpired?: boolean;
+}, flagLabels: {
+    keysFlag: string;
+    allowExpiredFlag: string;
+}): void;
+/** Each import/read-back SSH operation gets this deadline plus the SSH hard-kill grace. */
+export declare const AUTH_SYNC_PUSH_DEADLINE_MS = 20000;
+export interface AuthSyncDevice {
+    name: string;
+    reachable: boolean;
+    pinned: boolean;
+    remoteAuth: SharedAuthStatus | 'unknown';
+}
+export type AuthSyncPlanItem = {
+    action: 'push';
+    device: string;
+} | {
+    action: 'skip';
+    device: string;
+    reason: string;
+};
+export declare function planAuthBundlePush(localAuthOk: boolean, localIsPublisher: boolean, devices: AuthSyncDevice[]): AuthSyncPlanItem[];
+export interface AuthSyncResult {
+    publisher: string | null;
+    stateChanged: boolean;
+    pushed: string[];
+    skipped: Array<{
+        device: string;
+        reason: string;
+    }>;
+    errors: Array<{
+        device: string;
+        message: string;
+    }>;
+}
+export interface AuthSyncDeps {
+    inspectLocal?: () => {
+        exists: boolean;
+        ok: boolean;
+    };
+    listDevices?: () => DeviceProfile[];
+    localName?: string;
+    userAgentsDir?: string;
+    isPinned?: (name: string) => boolean;
+    push?: (bundle: string, host: string) => Promise<PushBundleResult>;
+    sshTarget?: (device: DeviceProfile) => string;
+}
+export interface PublishAuthVerdictOptions {
+    inspectLocal?: () => {
+        exists: boolean;
+        ok: boolean;
+    };
+    localName?: string;
+    userAgentsDir?: string;
+}
+export interface PublishAuthVerdictResult {
+    device: string;
+    status: SharedAuthStatus;
+    changed: boolean;
+    error: string | null;
+}
+/** Publish only safe readiness metadata; useful immediately before a repo push. */
+export declare function publishReservedAuthVerdict(options?: PublishAuthVerdictOptions): Promise<PublishAuthVerdictResult>;
+/**
+ * Publish local readiness, elect one ready source, then asynchronously provision
+ * only peers whose shared verdict says the bundle is missing.
+ */
+export declare function syncReservedAuthBundle(deps?: AuthSyncDeps): Promise<AuthSyncResult>;
+/** One account's durable worker credential, resolved to (bundle, key). */
+export interface ReservedSyncAccount {
+    accountId: string;
+    harness: AgentId;
+    /** Reserved store `__<harness>__`, or the legacy `auth` alias for a pre-T1 claude row. */
+    bundle: string;
+    /** Storage key `<ENV>_<accountId>` (or the legacy email-keyed claude key). */
+    key: string;
+    /**
+     * `workerCredential.mintedAt` -- a re-mint bumps it, so a delivered-memo hit on
+     * the old value re-pushes. `'legacy'` for a pre-T1 claude row with no field.
+     */
+    fingerprint: string;
+}
+/** A peer as the plan sees it: its role, reachability, and the keys it is KNOWN to hold. */
+export interface ReservedSyncPeer {
+    name: string;
+    /** `personal`/`desktop` -- receives the account row, never a durable key. */
+    headed: boolean;
+    reachable: boolean;
+    pinned: boolean;
+    /** bundle -> keys the peer already holds at the current fingerprint. Absent ⇒ none known. */
+    presentKeys: Record<string, ReadonlySet<string>>;
+}
+export type ReservedSyncPlanItem = {
+    action: 'push';
+    device: string;
+    bundle: string;
+    keys: string[];
+} | {
+    action: 'skip';
+    device: string;
+    reason: string;
+};
+/**
+ * Pure plan: for each worker peer, push each bundle it is missing at least one
+ * key of. Deterministic (peers and bundles sorted) so it pins exactly in tests.
+ * A headed peer is skipped BEFORE any key comparison -- it never receives a key.
+ */
+export declare function planReservedStoreSync(accounts: ReservedSyncAccount[], peers: ReservedSyncPeer[]): ReservedSyncPlanItem[];
+/**
+ * Every portable account's durable worker credential, resolved to (bundle, key).
+ * A T1 row carries `workerCredential`; a claude row predating T1 has none, so it
+ * falls back to the legacy `auth` bundle keyed by the account email -- the
+ * legacy fallback for claude rows that predate T1. An account with no derivable
+ * durable credential (per-device harness, or a non-claude row with no
+ * `workerCredential`) is not a sync target.
+ */
+export declare function reservedSyncTargets(meta: Pick<Meta, 'accounts' | 'deviceAccounts'>): ReservedSyncAccount[];
+export declare function readDeliveryMemo(root?: string): Record<string, string>;
+/**
+ * The keys a peer is KNOWN to hold, per bundle, from what we have delivered to it
+ * (memo, matched by fingerprint) plus the coarse legacy-`auth` verdict: a peer
+ * reporting `auth.status === 'ready'` is known to hold every legacy `auth` key.
+ * Reserved `__<harness>__` bundles have no coarse verdict, so their presence comes
+ * from the memo alone -- which is what makes a newly-added reserved account push.
+ */
+export declare function peerPresentKeys(peer: string, accounts: ReservedSyncAccount[], memo: Record<string, string>, legacyAuthReady: boolean): Record<string, ReadonlySet<string>>;
+export interface ReservedStoreSyncResult {
+    publisher: string | null;
+    pushed: Array<{
+        device: string;
+        bundle: string;
+        keys: string[];
+    }>;
+    skipped: Array<{
+        device: string;
+        reason: string;
+    }>;
+    errors: Array<{
+        device: string;
+        message: string;
+    }>;
+}
+export interface ReservedStoreSyncDeps {
+    listDevices?: () => DeviceProfile[];
+    localName?: string;
+    userAgentsDir?: string;
+    cacheDir?: string;
+    readMetaFn?: () => Pick<Meta, 'accounts' | 'deviceAccounts'>;
+    isPinned?: (name: string) => boolean;
+    peerRole?: (name: string) => ReturnType<typeof selfConfiguredDeviceRole>;
+    localReady?: boolean;
+    /** Does THIS publisher hold (bundle, key) to push? Defaults to a local bundle read. */
+    hasLocalKey?: (bundle: string, key: string) => boolean;
+    push?: (bundle: string, host: string) => Promise<PushBundleResult>;
+    sshTarget?: (device: DeviceProfile) => string;
+}
+/**
+ * Push every portable account's reserved store to the worker peers that are
+ * missing it, per key and per role. Reuses the same election as
+ * {@link syncReservedAuthBundle} (one deterministic ready publisher pushes) so
+ * there is no second scheduler. The daemon runs this each tick.
+ */
+export declare function syncReservedStores(deps?: ReservedStoreSyncDeps): Promise<ReservedStoreSyncResult>;
+export interface ReconcileWorkerSlotsResult {
+    provisioned: string[];
+    skipped: Array<{
+        accountId: string;
+        reason: string;
+    }>;
+    errors: Array<{
+        accountId: string;
+        message: string;
+    }>;
+}
+export interface ReconcileWorkerSlotsDeps {
+    selfRole?: ReturnType<typeof selfConfiguredDeviceRole>;
+    readMetaFn?: () => Pick<Meta, 'accounts' | 'deviceAccounts'>;
+    hasLocalKey?: (bundle: string, key: string) => boolean;
+    provision?: (account: NativeAccountRecord) => void;
+}
+/**
+ * Worker-side: after a durable key lands, materialize a slot for each portable
+ * account whose credential is now present locally. Runs only on a NON-headed
+ * (worker or unmarked) device -- a headed device provisions its slots from an
+ * interactive native login (`accounts add`), never from an injected durable key
+ * (invariant 7). Idempotent: an account already backed by a `durable` slot is
+ * skipped.
+ */
+export declare function reconcileLocalWorkerSlots(deps?: ReconcileWorkerSlotsDeps): ReconcileWorkerSlotsResult;