paranco

El permiso es más grande que la necesidad.

Algunas carpetas de un Mac están protegidas. Un programa que lee una de ellas necesita el Acceso total al disco. Ese ajuste no es un permiso sobre una sola carpeta. Abre todo lo que macOS protege de una vez.

La necesidad suele ser una sola carpeta. Un programa que quiera leer la biblioteca de Notas de voz necesitaría el Acceso total al disco para hacerlo directamente. Concedido a ese programa, el permiso llega también a cada intérprete o entorno de ejecución que cargue, a cada paquete instalado junto a él y a lo que esos paquetes carguen después. Nada de eso pidió el permiso.

paranco es lo más pequeño que conviene conceder. Lee una carpeta por ruta y escribe en una carpeta normal. Al programa que consume los archivos no se le concede nada, y sigue funcionando como antes.

Dos cosas que hace macOS y que dieron forma a esta herramienta.

Ambas se midieron. La primera explica por qué paranco es una aplicación y no un script. La segunda explica por qué distingue una carpeta vacía de una carpeta rechazada.

Una lista, no un archivo, decide qué se puede leer.

Cuatro hechos explican el diseño: qué es la lista, qué debe ser un destino, qué hace la copia y qué puede seguir haciendo un programa que se ejecute como tú.

paranco no tiene código de red. El código fuente no contiene ninguna sesión de URL, ningún socket ni ninguna comprobación de actualizaciones. No escribe nada en un origen. Mail, Mensajes y Safari no están en la lista, y no se añadirán.

Rutas, y un agente que las ejecuta.

Una ruta nombra un origen por identificador, una carpeta de destino y los archivos que incluye. No hay forma de decir «todo lo que hay bajo Library». El programa tiene un permiso que podría leer cualquier cosa, y lo usa para leer una sola cosa.

name          cómo se llama la ruta
sourceID      un identificador de la lista compilada, p. ej. "voice-memos"
destination   una carpeta normal, creada si no existe
extensions    en minúsculas, sin el punto; vacío significa la lista del propio origen
enabled       una ruta desactivada se conserva, pero nunca se ejecuta

Ejecutar una ruta

• Un archivo con el mismo nombre y el mismo tamaño ya está en el destino, y no se toca.
• Un archivo cuyo tamaño difiere se vuelve a copiar. Eso ocurre cuando una grabación todavía se estaba escribiendo la primera vez que se vio.
• Un archivo cuyo tamaño cambia entre dos comprobaciones, separadas dos segundos, todavía se está escribiendo. Se omite hasta la siguiente ejecución.
• Una ruta lleva los archivos normales del nivel superior de su origen. Omite los archivos ocultos y no entra en las subcarpetas.

El destino es el registro. Lo que hay allí es lo que se ha sacado, así que no hay una base de datos que pueda desincronizarse con la carpeta.

El agente

Un agente de launchd ejecuta cada ruta activada cada cinco minutos por defecto, y una vez al cargarse. Ejecuta el ejecutable propio de la aplicación con --agent. Cada ruta se ejecuta una vez, y el proceso termina. Imprime una línea solo cuando algo se ha copiado, ha fallado o ha sido rechazado. Esa salida va a agent.log, junto a routes.json.

El agente se instala desde la ventana, no desde la línea de comandos. El permiso pertenece al paquete de la aplicación, y la ventana es ese paquete.

El archivo de rutas

Las rutas están en ~/Library/Application Support/paranco/routes.json. Es un archivo JSON, así que se puede leer, comparar y editar con herramientas normales. Una ruta añadida en la ventana es la misma ruta que ven el agente y la línea de comandos. Un programa que lea este archivo debe seguir las notas de integración (en inglés).

Instalación

Necesitas macOS 14 o posterior, y una cadena de herramientas Swift 6 (Xcode 16 o las Command Line Tools correspondientes). No hay nada que descargar: la aplicación se compila desde el repositorio con un solo script.

git clone https://github.com/nerln/paranco
cd paranco
./build.sh

Eso deja Paranco.app en la carpeta del repositorio. La primera compilación genera también el icono, con make-icon.sh.

1. 1

   Concede el Acceso total al disco

   En Ajustes del Sistema (Configuración del Sistema en Latinoamérica), abre Privacidad y seguridad, luego Acceso total al disco (Acceso completo al disco en Latinoamérica), y añade Paranco.app. Ningún programa que lea los archivos copiados lo necesita. Es el único permiso que necesitan sus rutas. Otros programas pueden necesitarlo para su propio trabajo, por ejemplo el servicio de registro de paratia, que es un programa aparte.

2. 2

   Abre la aplicación

   open Paranco.app

3. 3

   Añade una ruta

   Elige un origen de la lista, hoy Notas de voz, y una carpeta de destino propia, por ejemplo ~/Recordings. La ventana comprueba el origen y dice cuál de las tres respuestas ha recibido.

4. 4

   Instala el agente

   Instálalo desde la ventana. A partir de entonces, el destino se llena solo en cada ejecución.

La línea de comandos

Compílalo con swift build -c release --product paranco. Eso deja el binario en .build/release/paranco. Los comandos siguientes usan paranco para ese binario.

paranco sources
paranco add voice-memos ~/Recordings --name memos --ext m4a,wav
paranco routes
paranco check
paranco lift
paranco agent status

Ejecutada desde una terminal, la línea de comandos usa el permiso de la terminal. Por eso un origen protegido aparece como rechazado allí, aunque se haya concedido el permiso a Paranco.app. Para rutas desde carpetas protegidas, usa la ventana o el agente. Instalar el agente no tiene forma de línea de comandos, a propósito.

swift test ejecuta las pruebas del núcleo. Cubren la copia, la regla de «ya está», el origen sin tocar, las comprobaciones del destino y la diferencia entre una carpeta rechazada y una vacía.

Límites

Estos límites también están en el README del proyecto (en inglés). Léelos antes de confiar en una garantía.

La familia

paranco es uno de dos pequeños programas del mismo autor. Ambos funcionan en el mismo Mac. Ninguno llama al otro, y paranco no lee los archivos de paratia.

paratia mantiene cifradas las carpetas que eliges, de modo que un agente de programación no pueda leerlas mientras están bloqueadas, y guarda un registro de quién abre o cambia los archivos que vigilas. También bloquea a los agentes mientras una carpeta está abierta, y cubre a dos agentes que juntos hacen lo que ninguno puede hacer solo.

paranco tiene el único permiso que copia archivos fuera de una carpeta protegida, así que ningún programa que lea las copias tiene que tenerlo. Copia en una sola dirección, siguiendo las rutas que configuras, y sus orígenes están escritos en el programa y no en un archivo.

Cada programa tiene su propia entrada en la lista de macOS, y cada uno necesita su propio permiso.

Son dos entradas separadas. El permiso de paranco no hace innecesario el de paratia.

Los dos programas comparten un archivo, routes.json. paratia puede leerlo sin cambiarlo, mediante su comando paratia registro rotte-paranco, en las versiones que incluyen ese comando. El comando propone vigilar las carpetas en las que escriben las rutas, así puedes ver quién abre los archivos copiados. Sin paratia, paranco no cambia.

Ninguno de los dos programas necesita al otro para funcionar.

Para leer más

• README (en inglés)Cómo funciona paranco, su modelo de seguridad y los pasos de instalación.
• Notas de integración (en inglés)Lo que otro programa puede dar por sentado en routes.json y en la carpeta de destino.
• Notas para agentes (llms.txt, en inglés)Notas de funcionamiento para agentes de programación.
• LICENSE (en inglés)MIT.
• paratiaEl programa hermano: carpetas cifradas para agentes de programación, y un registro de accesos.
• paratia en GitHubSu código fuente y los pasos de instalación. GPL-3.0.

Sobre el nombre

Un paranco es un aparejo: poleas y una cuerda para levantar una carga. El símbolo es una rueda, una cuerda y una carga. Junto a él, paratia es un mamparo estanco, un tabique que atraviesa el barco. Ambos son términos náuticos.