browxai 0.7.0

package/dist/util/credentials.d.ts

@@ -0,0 +1,136 @@
+import type { SecretRegistry } from "./secrets.js";
+export type ProviderName = "oathtool" | "1password" | "bitwarden" | "lastpass" | "none";
+export declare const ALL_PROVIDERS: readonly ProviderName[];
+/**
+ * Result of a TOTP lookup. `ok:false` carries a structured `error` + `hint`
+ * (typically the install / signin instruction) the tool layer surfaces back
+ * to the agent. The real code never appears in `error`.
+ */
+export interface TotpResult {
+    ok: boolean;
+    /** The 6 (or 8) digit one-time code, present iff `ok:true`. */
+    code?: string;
+    error?: string;
+    hint?: string;
+    /** Echo back the provider so the agent can confirm what backend answered. */
+    provider: ProviderName;
+}
+/**
+ * Result of a credential lookup. On success the `username` is plaintext —
+ * usernames aren't secret. The `password` is NEVER returned in cleartext;
+ * it's auto-registered into the per-session SecretRegistry under
+ * `aliasName`, and the caller substitutes it via `fill({value:"<NAME>"})`.
+ */
+export interface CredentialResult {
+    ok: boolean;
+    username?: string;
+    /** The SecretRegistry alias the password is registered under, e.g.
+     *  `PASSWORD_ACME`. The agent passes `<aliasName>` to `fill`/`press`; the
+     *  runtime materialises the real value at dispatch. NEVER the cleartext
+     *  password. */
+    aliasName?: string;
+    error?: string;
+    hint?: string;
+    provider: ProviderName;
+}
+/**
+ * The pluggable provider contract. Implementations are stateless w.r.t.
+ * browxai sessions — provider config lives in env / config file resolved
+ * at server start. `account` is the agent-facing identifier (e.g. an
+ * `op` item name, a Bitwarden item id, or an oathtool seed key); semantics
+ * are provider-specific.
+ */
+export interface CredentialProvider {
+    readonly name: ProviderName;
+    getTotp(account: string): Promise<TotpResult>;
+    getCredential(account: string): Promise<CredentialResult>;
+}
+interface RunResult {
+    ok: boolean;
+    stdout: string;
+    stderr: string;
+    code: number | null;
+    /** Set when the binary itself couldn't be spawned (ENOENT etc). */
+    spawnError?: string;
+}
+/** Spawn a process with fixed argv (no shell). Returns combined result.
+ *  Bounded by a 5s wall-clock — a hung CLI shouldn't block tool dispatch. */
+export declare function runArgv(argv: readonly string[], opts?: {
+    env?: NodeJS.ProcessEnv;
+    timeoutMs?: number;
+    stdin?: string;
+}): Promise<RunResult>;
+/** Turn an agent-facing account name into a SecretRegistry alias identifier.
+ *  Result always matches `/^[A-Z][A-Z0-9_]*$/`. */
+export declare function aliasFromAccount(account: string, prefix?: string): string;
+/**
+ * Seeds for the oathtool backend. The operator supplies seeds via env:
+ *   BROWX_OATHTOOL_SEEDS=acct1=BASE32SECRET,acct2=BASE32SECRET
+ * or via JSON file:
+ *   BROWX_OATHTOOL_SEEDS_FILE=/path/to/seeds.json   # {"acct1":"BASE32SECRET",…}
+ *
+ * Seeds are loaded ONCE at server start and held in memory. The seeds map
+ * is NOT exposed via any tool — the agent only ever knows the account
+ * name, never the seed. `get_credential` is not supported by this provider
+ * (oathtool is TOTP-only; pair with another vault for username/password).
+ */
+export interface OathtoolConfig {
+    binary?: string;
+    seeds: Readonly<Record<string, string>>;
+}
+/** Parse `acct1=SEED1,acct2=SEED2` into a record. Tolerates whitespace,
+ *  rejects malformed entries silently (returns what parses). Internal — the
+ *  full resolution flow surfaces a clean warning when nothing parses. */
+export declare function parseSeedsEnv(raw: string | undefined): Record<string, string>;
+/** Internal shape carrying the raw password out of a provider. The server
+ *  layer reads `_password`, registers it into SecretRegistry, and returns
+ *  the aliasName-bearing public shape. The `_password` field is stripped
+ *  before any response is serialised. */
+export type ProviderCredentialInternal = CredentialResult & {
+    _password?: string;
+};
+export interface CredentialsConfig {
+    provider: ProviderName;
+    warnings: readonly string[];
+}
+/**
+ * Resolve the configured provider from env. Returns the provider singleton
+ * + any non-fatal startup warnings (the caller logs these via `log.warn`).
+ *
+ * Env contract:
+ *   BROWX_CREDENTIALS_PROVIDER=oathtool|1password|bitwarden|lastpass|none
+ *   BROWX_OATHTOOL_BIN=/custom/path/to/oathtool
+ *   BROWX_OATHTOOL_SEEDS="acct1=BASE32,acct2=BASE32"
+ *   BROWX_1PASSWORD_BIN=/custom/path/to/op
+ *   BROWX_BITWARDEN_BIN=/custom/path/to/bw
+ *   BROWX_LASTPASS_BIN=/custom/path/to/lpass
+ *
+ * Default is `oathtool` (the self-managed, no-paid-dependency path). The
+ * provider object is constructed eagerly; if its CLI is missing, that
+ * surfaces per-call, never at startup (so the server still boots).
+ */
+export declare function resolveCredentialsProvider(env?: NodeJS.ProcessEnv): {
+    provider: CredentialProvider;
+    config: CredentialsConfig;
+};
+/**
+ * Test seam: build a provider instance directly from a callable pair.
+ * Used by the test suite to mock both endpoints without spawning a real
+ * binary. Not exported for runtime use.
+ */
+export declare function makeFakeProvider(impl: {
+    getTotp: (account: string) => Promise<TotpResult>;
+    getCredential: (account: string) => Promise<CredentialResult>;
+}, name?: ProviderName): CredentialProvider;
+/**
+ * Apply a credential lookup to the per-session secrets registry:
+ * registers the password under an account-derived alias, then returns the
+ * public credential shape (username + aliasName only, NEVER the password).
+ *
+ * Callers pass `registry` only when the `secrets` capability is enabled.
+ * When it's not, the function returns a structured refusal — registering
+ * a password without the egress-masking layer engaged would leak the
+ * password into transcripts the first time the agent referenced it.
+ */
+export declare function applyCredentialToRegistry(result: ProviderCredentialInternal, registry: SecretRegistry | null, account: string, pageUrl?: string): CredentialResult;
+export {};