@icarusmx/creta 1.5.14 → 1.5.16

package/lib/exercises/API_CHANGES.md

@@ -0,0 +1,193 @@
+# API Changes for Poetic Authentication
+
+## Endpoint to Modify
+
+**Location:** `icarus.mx/api/creta/testeo`
+
+This endpoint needs to be created/modified to handle the poetic key-value authentication pattern.
+
+---
+
+## Required Behavior
+
+### Request
+```bash
+curl -H "Authorization: Bearer es un secreto" https://icarus.mx/api/creta/testeo
+```
+
+### Response
+```json
+{
+  "message": "que a tu mirada y la mía la separa el abismo"
+}
+```
+
+Or as plain text:
+```
+que a tu mirada y la mía la separa el abismo
+```
+
+---
+
+## Implementation (SvelteKit Example)
+
+If the API is SvelteKit-based, create:
+
+**File:** `src/routes/api/creta/testeo/+server.js`
+
+```javascript
+// src/routes/api/creta/testeo/+server.js
+
+export async function GET({ request }) {
+  // Extract Authorization header
+  const authHeader = request.headers.get('Authorization');
+
+  // Check for the poetic key
+  if (authHeader === 'Bearer es un secreto') {
+    return new Response(
+      JSON.stringify({
+        message: "que a tu mirada y la mía la separa el abismo"
+      }),
+      {
+        status: 200,
+        headers: {
+          'Content-Type': 'application/json',
+          'Access-Control-Allow-Origin': '*'
+        }
+      }
+    );
+  }
+
+  // Unauthorized response
+  return new Response(
+    JSON.stringify({
+      error: "Unauthorized",
+      hint: "¿Conoces el secreto?"
+    }),
+    {
+      status: 401,
+      headers: {
+        'Content-Type': 'application/json'
+      }
+    }
+  );
+}
+
+// Handle OPTIONS for CORS
+export async function OPTIONS() {
+  return new Response(null, {
+    status: 204,
+    headers: {
+      'Access-Control-Allow-Origin': '*',
+      'Access-Control-Allow-Methods': 'GET, OPTIONS',
+      'Access-Control-Allow-Headers': 'Authorization, Content-Type'
+    }
+  });
+}
+```
+
+---
+
+## Implementation (Express.js Example)
+
+If using Express.js:
+
+```javascript
+// routes/api/creta.js
+
+router.get('/testeo', (req, res) => {
+  const authHeader = req.headers.authorization;
+
+  if (authHeader === 'Bearer es un secreto') {
+    return res.json({
+      message: "que a tu mirada y la mía la separa el abismo"
+    });
+  }
+
+  return res.status(401).json({
+    error: "Unauthorized",
+    hint: "¿Conoces el secreto?"
+  });
+});
+```
+
+---
+
+## Testing the Endpoint
+
+### Using curl
+```bash
+# Unauthorized (no key)
+curl https://icarus.mx/api/creta/testeo
+
+# Authorized (correct key)
+curl -H "Authorization: Bearer es un secreto" https://icarus.mx/api/creta/testeo
+```
+
+### Using lz function
+```bash
+# Without key
+lz icarus.mx/api/creta/testeo
+
+# With key
+export key="es un secreto"
+lz icarus.mx/api/creta/testeo
+```
+
+### Expected Outputs
+
+**Without key (401):**
+```json
+{
+  "error": "Unauthorized",
+  "hint": "¿Conoces el secreto?"
+}
+```
+
+**With correct key (200):**
+```json
+{
+  "message": "que a tu mirada y la mía la separa el abismo"
+}
+```
+
+---
+
+## Poetic Context
+
+This authentication pattern is inspired by romantic poetry - a playful way to teach API authentication concepts:
+
+- **Key:** "es un secreto" (it's a secret)
+- **Response:** "que a tu mirada y la mía la separa el abismo" (that separates your gaze and mine, the abyss)
+
+It makes learning authentication memorable and culturally relevant for Spanish-speaking students.
+
+---
+
+## Security Note
+
+**⚠️ This is for educational purposes only!**
+
+In production:
+- Never use predictable keys like "es un secreto"
+- Use proper JWT tokens or API keys with sufficient entropy
+- Implement rate limiting
+- Use HTTPS (already doing this)
+- Hash/encrypt sensitive data
+- Implement token expiration
+
+This endpoint is designed to teach the **concept** of Bearer token authentication in a memorable, culturally resonant way.
+
+---
+
+## Next Steps
+
+1. Deploy the endpoint to `icarus.mx/api/creta/testeo`
+2. Test with curl
+3. Test with `lz` function
+4. Update exercise documentation with live endpoint
+5. Consider adding to curl-and-pipes lesson (06-curl-and-pipes.md)
+
+---
+
+**Reference:** This endpoint supports the `lz` shell function taught in exercise 13-shell-aliases.md

package/lib/exercises/utils/README.md

@@ -0,0 +1,114 @@
+# Creta - Utilities for Exercises
+
+This directory contains ready-to-use shell functions and utilities that students can copy and use while learning with Creta.
+
+## Available Utilities
+
+### lz-functions.sh
+
+**Purpose:** API querying made simple with automatic API key management
+
+**What it provides:**
+- `lz [url]` - HTTP GET requests with automatic authentication
+- `headers [url]` - View HTTP headers
+- `post [url] [json]` - POST requests with JSON
+- `switch_key [env]` - Switch between dev/staging/prod keys
+- `show_key` - View current API key status (masked)
+- `lz_help` - Quick reference
+
+**Installation:**
+
+```bash
+# Option 1: Copy to home directory
+cp lib/exercises/utils/lz-functions.sh ~/.lz-functions.sh
+
+# Add to ~/.zshrc
+echo "source ~/.lz-functions.sh" >> ~/.zshrc
+
+# Reload
+source ~/.zshrc
+```
+
+**Usage:**
+
+```bash
+# Basic request
+lz icarus.mx
+
+# With authentication
+export key="sk_test_your_api_key"
+lz icarus.mx/api/endpoint
+
+# POST with JSON
+post icarus.mx/api/users '{"name":"Memo"}'
+
+# View headers
+headers icarus.mx/api/health
+
+# Switch environments
+switch_key dev
+switch_key prod
+switch_key clear  # Remove key
+
+# Check current key
+show_key
+```
+
+**Security Best Practices:**
+
+1. Never put API keys directly in `~/.zshrc`
+2. Create `~/.api_keys` with restrictive permissions:
+   ```bash
+   touch ~/.api_keys
+   chmod 600 ~/.api_keys
+   ```
+3. Add your keys to `~/.api_keys`:
+   ```bash
+   export key="your_api_key_here"
+   ```
+4. Source it from `~/.zshrc`:
+   ```bash
+   if [ -f ~/.api_keys ]; then
+     source ~/.api_keys
+   fi
+   ```
+5. Use `unset key` when done with sensitive APIs
+
+**Related Lessons:**
+- Exercise 13: Shell Functions - API Querying Simplificado
+- Exercise 06: Curl y pipes
+
+---
+
+## Adding New Utilities
+
+When creating new utilities for exercises:
+
+1. Create a descriptive filename (e.g., `git-helpers.sh`)
+2. Add comprehensive comments explaining:
+   - What it does
+   - How to install it
+   - How to use it
+   - Examples
+3. Update this README with the new utility
+4. Reference it from the relevant exercise
+
+## Philosophy
+
+These utilities are **learning tools**, not production code:
+- Simple over clever
+- Well-commented
+- Easy to understand
+- Ready to copy-paste
+- Safe defaults
+
+Students should be able to:
+1. Copy the file
+2. Understand what it does
+3. Customize it for their needs
+4. Learn from the code
+
+---
+
+**Maintained by:** Icarus Software School
+**License:** MIT (educational use)

package/lib/exercises/utils/lz-functions.sh

@@ -0,0 +1,240 @@
+#!/usr/bin/env zsh
+
+# ==============================================================================
+# lz - API Querying Simplificado con manejo automático de API keys
+# ==============================================================================
+#
+# Instalación:
+#   1. Copia este archivo a ~/.lz-functions.sh
+#   2. Agrega a tu ~/.zshrc:
+#      source ~/.lz-functions.sh
+#   3. Recarga: source ~/.zshrc
+#
+# Uso básico:
+#   lz icarus.mx                    # Request normal
+#   export key="es un secreto"      # Define API key (poético)
+#   lz icarus.mx/api/creta/testeo   # Request con autenticación automática
+#   unset key                       # Elimina la key (seguridad)
+#
+# ==============================================================================
+
+# ------------------------------------------------------------------------------
+# lz() - Función principal para hacer requests HTTP
+# ------------------------------------------------------------------------------
+# Detecta automáticamente si la variable $key está definida y agrega el header
+# de autorización. Acepta URLs con o sin protocolo (agrega https:// si falta).
+#
+# Ejemplos:
+#   lz icarus.mx
+#   lz icarus.mx/api/endpoint
+#   lz https://api.ejemplo.com/data
+# ------------------------------------------------------------------------------
+lz() {
+  local url="$1"
+
+  # Validar que se pasó una URL
+  if [ -z "$url" ]; then
+    echo "❌ Uso: lz [url]"
+    echo "Ejemplo: lz icarus.mx/api/endpoint"
+    return 1
+  fi
+
+  # Si la URL no tiene protocolo, agregar https://
+  if [[ ! "$url" =~ ^https?:// ]]; then
+    url="https://$url"
+  fi
+
+  # Si hay API key exportada, incluirla en el header
+  if [ -n "$key" ]; then
+    echo "🔑 Request con autenticación a: $url"
+    curl -H "Authorization: Bearer $key" "$url"
+  else
+    echo "🌐 Request sin autenticación a: $url"
+    curl "$url"
+  fi
+}
+
+# ------------------------------------------------------------------------------
+# headers() - Ver solo los headers de un endpoint
+# ------------------------------------------------------------------------------
+# Wrapper de lz con flag -I para ver headers HTTP
+#
+# Ejemplos:
+#   headers icarus.mx
+#   headers api.ejemplo.com/health
+# ------------------------------------------------------------------------------
+headers() {
+  local url="$1"
+
+  if [ -z "$url" ]; then
+    echo "❌ Uso: headers [url]"
+    return 1
+  fi
+
+  # Agregar https:// si falta
+  if [[ ! "$url" =~ ^https?:// ]]; then
+    url="https://$url"
+  fi
+
+  if [ -n "$key" ]; then
+    curl -I -H "Authorization: Bearer $key" "$url"
+  else
+    curl -I "$url"
+  fi
+}
+
+# ------------------------------------------------------------------------------
+# post() - Hacer POST request con JSON
+# ------------------------------------------------------------------------------
+# Envía datos JSON a un endpoint. Incluye API key automáticamente si existe.
+#
+# Ejemplos:
+#   post icarus.mx/api/users '{"name":"Guillermo"}'
+#   export key="es un secreto"
+#   post icarus.mx/api/creta/testeo '{"message":"hola"}'
+# ------------------------------------------------------------------------------
+post() {
+  local url="$1"
+  local data="$2"
+
+  if [ -z "$url" ] || [ -z "$data" ]; then
+    echo "❌ Uso: post [url] [json]"
+    echo "Ejemplo: post icarus.mx/api/users '{\"name\":\"Memo\"}'"
+    return 1
+  fi
+
+  # Agregar https:// si falta
+  if [[ ! "$url" =~ ^https?:// ]]; then
+    url="https://$url"
+  fi
+
+  if [ -n "$key" ]; then
+    echo "🔑 POST con autenticación a: $url"
+    curl -X POST \
+         -H "Authorization: Bearer $key" \
+         -H "Content-Type: application/json" \
+         -d "$data" \
+         "$url"
+  else
+    echo "🌐 POST sin autenticación a: $url"
+    curl -X POST \
+         -H "Content-Type: application/json" \
+         -d "$data" \
+         "$url"
+  fi
+}
+
+# ------------------------------------------------------------------------------
+# switch_key() - Cambiar entre diferentes API keys
+# ------------------------------------------------------------------------------
+# Útil cuando trabajas con múltiples ambientes (dev, staging, prod).
+# Personaliza los casos según tus necesidades.
+#
+# Ejemplos:
+#   switch_key dev
+#   switch_key prod
+#   switch_key staging
+# ------------------------------------------------------------------------------
+switch_key() {
+  case "$1" in
+    dev)
+      export key="sk_test_desarrollo_placeholder"
+      echo "✅ API key: desarrollo"
+      ;;
+    staging)
+      export key="sk_test_staging_placeholder"
+      echo "✅ API key: staging"
+      ;;
+    prod)
+      export key="sk_live_produccion_placeholder"
+      echo "⚠️  API key: producción (¡cuidado!)"
+      ;;
+    clear)
+      unset key
+      echo "🧹 API key eliminada"
+      ;;
+    *)
+      echo "❌ Uso: switch_key [dev|staging|prod|clear]"
+      return 1
+      ;;
+  esac
+}
+
+# ------------------------------------------------------------------------------
+# show_key() - Mostrar el estado actual de la API key
+# ------------------------------------------------------------------------------
+# Útil para verificar qué key está activa sin exponer su valor completo.
+#
+# Ejemplos:
+#   show_key
+# ------------------------------------------------------------------------------
+show_key() {
+  if [ -n "$key" ]; then
+    # Mostrar solo los primeros 10 caracteres (seguridad)
+    local masked_key="${key:0:10}***"
+    echo "🔑 API key activa: $masked_key"
+  else
+    echo "❌ No hay API key definida"
+    echo "💡 Define una con: export key=\"tu_api_key\""
+  fi
+}
+
+# ------------------------------------------------------------------------------
+# lz_help() - Ayuda rápida
+# ------------------------------------------------------------------------------
+lz_help() {
+  cat << 'EOF'
+╔══════════════════════════════════════════════════════════════╗
+║  lz - API Querying Simplificado                              ║
+╚══════════════════════════════════════════════════════════════╝
+
+📚 Funciones disponibles:
+
+  lz [url]              Request GET con autenticación automática
+  headers [url]         Ver solo headers HTTP
+  post [url] [json]     POST request con JSON
+  switch_key [env]      Cambiar entre dev/staging/prod/clear
+  show_key              Ver estado de la API key actual
+
+🔐 Gestión de API keys:
+
+  export key="sk_..."   Define API key para la sesión
+  unset key             Elimina API key (seguridad)
+  switch_key dev        Cambia a ambiente de desarrollo
+  switch_key clear      Elimina la key actual
+
+💡 Ejemplos:
+
+  # Request normal
+  lz icarus.mx
+
+  # Request con autenticación (poético)
+  export key="es un secreto"
+  lz icarus.mx/api/creta/testeo
+  # Responde: "que a tu mirada y la mía la separa el abismo"
+
+  # Ver headers
+  headers icarus.mx/api/health
+
+  # POST con JSON
+  post icarus.mx/api/users '{"name":"Guillermo"}'
+
+  # Combinar con jq para parsear JSON
+  lz icarus.mx/api/data | jq '.results'
+
+🔒 Seguridad:
+
+  ❌ NUNCA pongas keys en ~/.zshrc directamente
+  ✅ Usa ~/.api_keys con permisos 600
+  ✅ Agrega a ~/.zshrc: source ~/.api_keys
+  ✅ Usa unset key al terminar
+
+📖 Más info: creta help lz
+
+EOF
+}
+
+# ------------------------------------------------------------------------------
+# Mensaje de bienvenida (opcional - comenta si no lo quieres)
+# ------------------------------------------------------------------------------
+# echo "✅ lz functions cargadas. Usa 'lz_help' para ayuda."