fn_registry/docs/capabilities/browser-profiles.md

Capability: browser-profiles

Catálogo operativo de los perfiles del navegador Chromium para investigaciones multicuenta OSINT. Por cada perfil de Chromium (un --profile-directory dentro de un user-data-dir) guarda qué correo/cuentas usar, propósito, persona e identidad de la investigación y la nota del vault que lo documenta, y permite lanzar el perfil listo para trabajar mostrando sus cuentas. La fuente de verdad vive en el service osint_db (FastAPI + DuckDB, http://127.0.0.1:8771), en las tablas browser_profiles + browser_profile_accounts (schema main, pobladas solo por API, como network_scans). Estas funciones son clientes HTTP finos a ese service.

Regla de seguridad dura: una cuenta guarda secret_ref — una referencia al secreto (ej. pass show osint/p1/gmail), NUNCA la contraseña en claro. Ni el service ni estas funciones almacenan o resuelven credenciales: browser_profile_open solo expone el secret_ref para que el operador (o otra herramienta) lo resuelva con pass/keepass.

Comparte el ecosistema del project osint (vault Obsidian + service osint_db) con los grupos recon, osint-passive y dav. El perfil real de Chromium vive en ~/.config/chromium-cdp (user-data-dir con CDP 9222 inyectado por el wrapper /usr/bin/chromium); el catálogo NO toca el perfil en disco, solo su metadata.

Funciones

ID	Firma	Qué hace
browser_profile_register_py_browser	browser_profile_register(profile_dir, label="", persona="", purpose="", note_path="", tags=None, notes="", user_data_dir="", status="active", accounts=None, base_url=...) -> dict	Registra/actualiza un perfil y, opcionalmente, sus cuentas en una sola llamada (1 POST del perfil + 1 POST por cuenta). Idempotente (upsert por profile_dir y por id de cuenta). accounts es una lista de dicts {service, identity, secret_ref?, role?, status?, notes?}.
browser_profile_list_py_browser	browser_profile_list(status=None, base_url=...) -> dict	Lista los perfiles del catálogo con su nº de cuentas (n_accounts). Filtro opcional por status (active/archived). Devuelve {"status":"ok","profiles":[...]}.
browser_profile_show_py_browser	browser_profile_show(profile_dir, base_url=...) -> dict	Muestra un perfil con todas sus cuentas. Devuelve {"status":"ok","profile":{...},"accounts":[...]} o error si no existe. Las cuentas traen secret_ref (referencia), nunca el password.
browser_profile_open_py_browser	browser_profile_open(profile_dir, url=None, base_url=..., dry_run=False) -> dict	Lanza Chromium en el perfil (--profile-directory) vía systemd-run --user --scope (evita exit-144) y devuelve sus cuentas/secret_ref para saber qué usar. dry_run=True devuelve el comando sin abrir nada. Compone browser_profile_show para leer la metadata.

Ejemplo canónico (end-to-end)

import sys, os
sys.path.insert(0, os.path.join("python", "functions"))
from browser.browser_profile_register import browser_profile_register
from browser.browser_profile_list import browser_profile_list
from browser.browser_profile_show import browser_profile_show
from browser.browser_profile_open import browser_profile_open

# 1. Registrar un perfil con sus cuentas (secret_ref = referencia a pass, NO el password)
browser_profile_register(
    "osint_01",
    label="osint_01",
    persona="sock-puppet Marta R.",
    purpose="infiltración foros nicho X",
    tags=["osint", "sockpuppet"],
    accounts=[
        {"service": "gmail",    "identity": "marta.r.osint@gmail.com", "secret_ref": "pass show osint/osint_01/gmail", "role": "primary"},
        {"service": "twitter",  "identity": "@marta_r_osint",         "secret_ref": "pass show osint/osint_01/x",     "role": "burner"},
    ],
)

# 2. Listar el catálogo
browser_profile_list()                       # {"status":"ok","profiles":[{profile_dir, label, n_accounts, ...}]}

# 3. Ver un perfil con sus cuentas
browser_profile_show("osint_01")             # {"profile": {...}, "accounts": [{service, identity, secret_ref, role}]}

# 4. Abrir el perfil listo para trabajar (lanza Chromium + dice qué cuentas usar)
browser_profile_open("osint_01", url="https://twitter.com")
#   -> systemd-run --user --scope -- chromium --profile-directory=osint_01 https://twitter.com
#   -> accounts: [(gmail, pass show osint/osint_01/gmail), (twitter, pass show osint/osint_01/x)]

Vía fn run (un id conocido a la vez):

./fn run browser_profile_list
./fn run browser_profile_show osint_01
./fn run browser_profile_open osint_01 https://twitter.com

Fronteras (qué NO cubre)

• No gestiona el perfil de Chromium en disco (crear/clonar/extensiones/avatar): eso es create_chrome_profile_bash_browser, list_chrome_profiles_go_browser, set_chrome_profile_appearance_bash_browser. Este grupo solo guarda metadata operativa y lanza un perfil existente.
• No almacena ni resuelve contraseñas. Solo referencias (secret_ref). El password se resuelve aparte con pass/keepass.
• No automatiza el login ni rellena formularios: para eso usa el browser_mcp o el grupo flow-replay una vez el perfil está abierto.
• Requiere el service osint_db vivo en :8771. Si está caído, las funciones devuelven {"status":"error", ...} sin lanzar.

Gotchas

• El profile_dir es el nombre del directorio REAL del perfil de Chromium (lo que va en --profile-directory): "Default", "Profile 1", "osint_01". NO es el nombre legible (ese es label). Verlos con list_chrome_profiles_go_browser o el Local State del user-data-dir.
• browser_profile_open por defecto NO pasa --user-data-dir (el perfil vive en ~/.config/chromium-cdp, que el wrapper /usr/bin/chromium ya inyecta). Si el perfil está en otro user-data-dir, regístralo con user_data_dir=<ruta> y la función lo pasará explícito.
• Se lanza vía systemd-run --user --scope a propósito: lanzar Chromium directo desde un proceso hijo da exit-144 en este entorno.
• secret_ref NUNCA es el password. Si te ves tentado a meter la contraseña ahí, para: guárdala en pass/keepass y referencia el comando.