---
name: apply_chromium_extension_policy
kind: function
lang: bash
domain: browser
version: "1.1.0"
purity: impure
signature: "apply_chromium_extension_policy [--keep <ext_id[=update_url]>]... [--block <ext_id>]... [--policy-path <path>] [--update-url <url>] [--dry-run]"
description: "Escribe de forma idempotente la política managed de Chromium combinando ExtensionInstallForcelist (force-instala la whitelist --keep) y ExtensionInstallBlocklist (bloquea y desinstala la blocklist --block). No usa el comodín \"*\" blocked, por lo que NO afecta a las extensiones unpacked cargadas con --load-extension. Guarda backup fuera del directorio managed/ (que Chromium lee entero). Requiere sudo para escribir en /etc; en --dry-run no toca el sistema."
tags: [chromium, extensions, policy, browser, navegator, managed-policy, idempotent]
uses_functions: []
uses_types: []
returns: []
returns_optional: false
error_type: "error_go_core"
imports: []
params:
  - name: "--keep <ext_id[=update_url]>"
    desc: "ID de extensión a force-instalar (repetible). Va a ExtensionInstallForcelist. Forma simple '<id>' usa el update_url por defecto (Web Store). Forma '<id>=<update_url>' fuerza una extensión self-hosted: por ejemplo '<id>=file:///home/u/.web_proxy/update.xml' instala un .crx local empaquetado bajo managed policy (necesario porque --load-extension queda desactivado cuando hay managed policy). Ejemplo Web Store: ddkjiahejlhfcafbddmgiahcphecmpfh (uBlock Origin Lite)."
  - name: "--block <ext_id>"
    desc: "ID de extensión a bloquear y desinstalar en cualquier perfil (repetible). Va a ExtensionInstallBlocklist. Solo afecta a los IDs listados; el resto de extensiones no se toca."
  - name: "--policy-path <path>"
    desc: "Ruta del JSON de managed policy. Default: /etc/chromium/policies/managed/extensions.json."
  - name: "--update-url <url>"
    desc: "URL del servicio de actualización de extensiones. Default: https://clients2.google.com/service/update2/crx."
  - name: "--dry-run"
    desc: "Imprime el JSON que se escribiría sin tocar el sistema (no requiere sudo)."
output: "Escribe el JSON de política en policy-path y emite a stdout un resumen: extensiones forzadas, bloqueadas, ruta, backup creado y recordatorio de reinicio de Chromium. Sale 0 si la política se aplicó o ya estaba vigente. Sale != 0 en error. Requiere al menos un --keep o --block."
tested: false
tests: []
test_file_path: ""
file_path: "bash/functions/browser/apply_chromium_extension_policy.sh"
---

## Ejemplo

```bash
# Dejar el perfil con solo uBlock Origin Lite: forzar uBlock + bloquear las 3 que estorban
# al scraping (Dark Reader, NoScript, OneTab). Proyecto web_scraping, regla 9.
source bash/functions/browser/apply_chromium_extension_policy.sh
apply_chromium_extension_policy \
    --keep  ddkjiahejlhfcafbddmgiahcphecmpfh \
    --block eimadpbcbfnmbkopoojfekhnkhdbieeh \
    --block doojmbjmlfjjnbmnoijecmcbfeoakpjm \
    --block chphlpgkkbolifaimnlloiipkdnihall

# Previsualizar sin tocar el sistema (sin sudo)
apply_chromium_extension_policy --keep ddkjiahejlhfcafbddmgiahcphecmpfh --dry-run

# Ejecutar como root para el sudo no interactivo de este equipo
pass show claude/sudo | sudo -S bash bash/functions/browser/apply_chromium_extension_policy.sh \
    --keep ddkjiahejlhfcafbddmgiahcphecmpfh --block eimadpbcbfnmbkopoojfekhnkhdbieeh
```

La policy por sí sola evita la reinstalación pero NO desinstala lo ya presente en un perfil concreto:
combínala con `clean_chrome_profile_extensions_bash_browser` (con Chromium cerrado) para purgar del
disco las extensiones ya instaladas.

## Cuando usarla

Al preparar un PC nuevo o cambiar qué extensiones de Chrome Web Store deben estar (o no estar) en
cualquier perfil de Chromium del equipo. Reemplaza el paso manual de editar el JSON de policy con
sudo. `--keep` fuerza y fija las imprescindibles; `--block` elimina las molestas sin tocar el resto.

## Gotchas

- **El backup NUNCA va dentro de `managed/`** (lo gestiona la función, pero es la lección clave): Chromium
  lee **todos** los archivos del directorio `policies/managed/` sin filtrar por extensión de nombre. Un
  `extensions.json.bak.YYYYMMDD` dentro de `managed/` se mergea con la policy efectiva y **reinyecta** las
  extensiones del backup (se ven como `location=7` external_policy_download y vuelven aunque las borres).
  Por eso la función guarda los backups en `policies/policy-backups/`, fuera de `managed/`. Si encuentras
  backups antiguos dentro de `managed/`, muévelos fuera.
- **No usa el comodín `"*": blocked`**: ese modo desinstala todo lo no-whitelist pero también **bloquea las
  extensiones unpacked** (`--load-extension`), rompiendo cosas como la extensión de captura de `web_proxy`
  con el error "Loading of unpacked extensions is disabled by the administrator". Esta función bloquea solo
  los IDs de `--block`.
- **`--load-extension` y managed policy son incompatibles en Chromium 137+**: con CUALQUIER managed policy
  presente, Chromium desactiva `--load-extension` ("disabled by the administrator"). Para cargar una
  extensión local junto a una managed policy hay que empaquetarla (.crx + update_url) o usar `--proxy-server`
  directo en el caso de `web_proxy`.
- **Requiere sudo** para escribir en `/etc/chromium/policies/managed/`. En este equipo: `pass show claude/sudo | sudo -S <cmd>`.
- **Chrome cachea la política en memoria**: cerrar TODOS los Chromium (`pkill -9 chromium`) y relanzar, o `chrome://policy` → "Reload policies".
- **Idempotente**: si el archivo ya tiene el mismo contenido, no-op y sale 0.
- Referencia del sistema completo: `projects/web_scraping/CHROMIUM_SYSTEM.md`.

## Capability growth log

- v1.2.0 (2026-06-05) — `--keep` acepta `<id>=<update_url>` para force-instalar extensiones self-hosted (p.ej. un `.crx` local vía `file://` a un `update.xml`), que es la forma de cargar una extensión propia cuando hay managed policy y `--load-extension` está desactivado.
- v1.1.0 (2026-06-05) — añade `--block` (ExtensionInstallBlocklist); reemplaza el modo `ExtensionSettings "*": blocked` (rompía extensiones unpacked) por blocklist específica; mueve los backups fuera de `managed/` (Chromium lee todo el directorio y un `.bak` ahí reinyectaba extensiones).
- v1.0.0 (2026-06-05) — baseline: ExtensionInstallForcelist con whitelist `--keep`.
