import: contenido inicial de la skill bitwarden

2026-04-26 14:22:15 -06:00
parent 976454dc79
commit 5534ab954c
9 changed files with 872 additions and 1 deletions
--- a/endpoints.md
+++ b/endpoints.md
@@ -0,0 +1,126 @@
+# Bitwarden `bw serve` — endpoint cheat sheet
+
+Base URL: `http://127.0.0.1:8087` (puerto en `BW_PORT`).
+Todos los endpoints devuelven `{ success: true|false, data?: ..., message?: ... }`.
+
+## Lectura (GET) — siempre permitida
+
+### Estado y metadata
+| Endpoint | Devuelve |
+|---|---|
+| `GET /status` | `{ object, status: locked\|unlocked, serverUrl, userEmail, userId, lastSync }` |
+| `GET /sync` | Fuerza sync con el server. `{ object: "message", title: "Syncing complete." }` |
+| `GET /object/fingerprint/me` | Fingerprint phrase de la cuenta |
+
+### Listas
+| Endpoint | Filtros (querystring) |
+|---|---|
+| `GET /list/object/items` | `search`, `url`, `folderid`, `collectionid`, `organizationid`, `trash` |
+| `GET /list/object/folders` | `search` |
+| `GET /list/object/collections` | `search`, `organizationid` |
+| `GET /list/object/org-collections` | `organizationid` (requerido) |
+| `GET /list/object/org-members` | `organizationid` (requerido) |
+| `GET /list/object/organizations` | `search` |
+| `GET /list/object/sends` | `search` |
+
+### Objeto específico (por id o por search exact-match en name)
+| Endpoint | Notas |
+|---|---|
+| `GET /object/item/<id\|name>` | Item completo (login/note/card/identity) |
+| `GET /object/folder/<id\|name>` | Folder |
+| `GET /object/collection/<id>` | Collection (personal o org) |
+| `GET /object/org-collection/<id>?organizationid=X` | Collection del org con detalles de members |
+| `GET /object/send/<id\|name>` | Send |
+| `GET /object/password/<item-id>` | **Sólo el password en plaintext** |
+| `GET /object/username/<item-id>` | Sólo el username |
+| `GET /object/uri/<item-id>` | Primera URI del item |
+| `GET /object/totp/<item-id>` | Código TOTP actual (si el item tiene `login.totp` configurado) |
+| `GET /object/notes/<item-id>` | Texto de la nota |
+| `GET /object/exposed/<item-id>` | Cuántas veces el password apareció en HIBP |
+| `GET /object/attachment/<attachment-id>?itemid=X&output=path` | Descarga el attachment |
+| `GET /object/template/<type>` | Template JSON para crear (`item`, `item.login`, `item.card`, `item.identity`, `item.securenote`, `folder`, `collection`, `send.text`, `send.file`, `org-collection`) |
+
+### Generador
+| Endpoint | Querystring |
+|---|---|
+| `GET /generate` | `length=20`, `uppercase`, `lowercase`, `numbers`, `special`, `passphrase=true`, `words=3`, `separator=-`, `capitalize`, `number` |
+
+Ejemplo: `GET /generate?length=24&uppercase&lowercase&numbers&special`
+
+## Creación (POST) — permitida en endpoints específicos
+
+| Endpoint | Body | Devuelve |
+|---|---|---|
+| `POST /object/item` | item JSON (ver `GET /object/template/item`) | item creado con `id`, `revisionDate` |
+| `POST /object/folder` | `{ "name": "..." }` | folder con `id` |
+| `POST /object/send` | send JSON (`GET /object/template/send.text` o `send.file`) | send con `id`, `accessUrl` |
+| `POST /object/org-collection?organizationid=X` | collection JSON | requiere permisos en el org (claudecode0 = "Can view" → 403) |
+
+### Auth/utility (también POST permitido)
+| Endpoint | Body | Notas |
+|---|---|---|
+| `POST /sync` | (vacío) | Equivalente a GET /sync |
+| `POST /unlock` | `{ "password": "..." }` o vía `BW_SESSION` env | Devuelve nueva session |
+| `POST /lock` | (vacío) | Lockea el vault. Requiere unlock para volver a usar |
+| `POST /generate` | `{ length, uppercase, ... }` | Equivalente a GET /generate |
+
+### Schema mínimo de item (type 1 = login)
+```json
+{
+  "organizationId": null,
+  "folderId": null,
+  "type": 1,
+  "name": "GitHub",
+  "notes": "personal account",
+  "favorite": false,
+  "fields": [
+    { "name": "Custom Field", "value": "x", "type": 0 }
+  ],
+  "login": {
+    "uris": [{ "uri": "https://github.com", "match": null }],
+    "username": "user",
+    "password": "***",
+    "totp": "otpauth://totp/..."
+  }
+}
+```
+
+Tipos: `1`=Login, `2`=SecureNote, `3`=Card, `4`=Identity.
+
+Para SecureNote usar `"type": 2` + `"secureNote": { "type": 0 }` en lugar de `login`.
+
+Pedí `GET /object/template/item.login` (o `.card`, `.identity`, `.securenote`) para el schema exacto antes de POST.
+
+## Bloqueado por la skill (read+create only)
+
+| Verbo / endpoint | Por qué |
+|---|---|
+| `PUT /object/*` | Modifica items existentes |
+| `DELETE /object/*` | Soft-delete (a Trash) |
+| `POST /restore/item/<id>` | Restaura desde Trash |
+| `POST /move/<ids>/<orgId>` | Comparte item al org |
+| `POST /confirm/org-member/<id>` | Confirma member invite |
+| `POST /object/attachment` (multipart) | Adjuntar archivos |
+| `POST /object/share/*` | Si existe, comparte items |
+
+Si **realmente** necesitás bypass-ear el guard (ej. cleanup), pidiéndoselo al usuario:
+```bash
+BITWARDENCLI_APPDATA_DIR=~/.claude/skills/bitwarden/.cache/bw \
+  BW_SESSION=$(cat ~/.claude/skills/bitwarden/.cache/session) \
+  bw <delete|edit|...>
+```
+
+## Códigos de error comunes
+
+| HTTP | Causa | Qué hacer |
+|---|---|---|
+| 401 | Vault locked o session expirada | Re-correr `setup.sh` para re-unlock |
+| 403 | Server side permission (rol "Can view" rechaza writes) | Esperado para acciones write en collections del org |
+| 404 | Item/folder/collection no existe (o no tiene acceso) | Verificar id |
+| 400 | Body JSON inválido | Pedí `GET /object/template/<type>` para el schema |
+| 500 | bw serve crasheó | `serve-down.sh && serve-up.sh`, ver `.cache/serve.log` |
+
+## Referencias
+- Doc oficial CLI: https://bitwarden.com/help/cli/
+- Vault Management API spec: https://bitwarden.com/help/vault-management-api/
+- Vaultwarden compat: https://github.com/dani-garcia/vaultwarden