Karibe Integration

Karibe is the Registry of Property (RIDPR) portal for Puerto Rico. This integration handles:

• Email verification code extraction for automated login
• PDF document downloads from the registry
• Document archival to S3

System Overview

External Systems              AWS Services              Data Stores
-----------------            --------------            ------------

    Client
      |
      | HTTPS + X-Secret
      v
+-------------------+
|   API Gateway     |
|   (HTTP API v2)   |
|   "karibe"        |
+--------+----------+
         |
         | Every request
         v
+---------------------+         +------------------+
|  karibe-authorizer  |-------->|  Secrets Manager |
|   (Lambda)          |         |  X-Secret value  |
+--------+------------+         +------------------+
         |
         | {"isAuthorized": true/false}
         v
+---------------------------------------+
|         If Authorized:                |
|                                       |
|  +--------------------------------+   |
|  |   Backend Lambda Functions     |   |
|  |                                |   |
|  |  +-------------------------+   |   |
|  |  | get-latest-karibe-codes |---+---+-> DynamoDB
|  |  |                         |   |   |   karibe_verification_codes
|  |  +-------------------------+   |   |
|  |                                |   |
|  |  +-------------------------+   |   |
|  |  | get-latest-emails       |---+---+-> S3
|  |  |                         |   |   |   alianza-ses-mail
|  |  +-------------------------+   |   |
|  +--------------------------------+   |
+---------------------------------------+

Background Processors:

  SES Email --> S3 --> karibe-code-extractor --> DynamoDB
                        (S3 event trigger)

  SQS --> karibe-fetcher --> Download PDF --> S3
                                              alianza-karibe-prod

Lambda Functions

karibe-authorizer

Property	Value
Type	API Gateway Lambda Authorizer
Runtime	Python 3.12
Trigger	API Gateway (every request)
Timeout	10 seconds
Memory	128 MB

Validates X-Secret header before allowing API requests.

get-latest-karibe-codes

Property	Value
Type	API Endpoint
Runtime	Python 3.12
Trigger	API Gateway GET /latest-codes
Timeout	30 seconds
Memory	128 MB

Query DynamoDB for recent verification codes.

Query Parameters:

• to (optional): Filter by recipient email
• limit (optional): Number of results (1-50, default 10)

Response:

{
  "filter": {"to": "user@domain.com"},
  "count": 5,
  "items": [
    {
      "code": "ABC123",
      "to": "user@domain.com",
      "subject": "Your Code",
      "created_at": "2025-10-23T12:00:00Z",
      "message_id": "<abc@domain.com>"
    }
  ]
}

get-latest-emails

Property	Value
Type	API Endpoint
Runtime	Python 3.12
Trigger	API Gateway GET /emails
Timeout	30 seconds
Memory	256 MB

List S3 emails filtered by recipient.

Query Parameters:

• to (required): Recipient email address
• limit (optional): Number of results (1-50, default 10)
• domain (optional): Override S3 prefix
• include=content (optional): Include email content

karibe-code-extractor

Property	Value
Type	Background Processor
Runtime	Python 3.12
Trigger	S3 event (new email)
Timeout	60 seconds
Memory	256 MB

Extract verification codes from emails and store in DynamoDB.

karibe-fetcher

Property	Value
Type	Background Processor
Runtime	Node.js 22.x
Trigger	SQS message
Timeout	60 seconds
Memory	256 MB

Download PDFs from Karibe website and store in S3.

Data Storage

DynamoDB Schema

Table: karibe_verification_codes

Primary Key:
  message_id (String) - HASH
  code (String) - RANGE

Attributes:
  to (String) - Recipient email
  to_norm (String) - Normalized (lowercase) email
  subject (String) - Email subject
  created_at (String) - ISO 8601 timestamp
  gsi_pk (String) - Always "code" for GSI partitioning

GSI 1: gsi_pk-created_at-index
  Purpose: Global latest codes query

GSI 2: gsi_to_created_at
  Purpose: Recipient-specific queries

S3 Buckets

Bucket	Purpose	Structure
alianza-ses-mail	Incoming emails from SES	{domain}/{year}/{month}/{day}/{message-id}.eml
alianza-karibe-prod	Downloaded PDF documents	karibe/cargados/{year-month}/{filename}.pdf

API Endpoints

Base URL: https://api.alianzacap.com

Route	Method	Lambda	Auth	Purpose
/latest-codes	GET	get-latest-karibe-codes	X-Secret	Query codes
/emails	GET	get-latest-emails	X-Secret	List emails

Authentication

All API requests require the X-Secret header:

curl -H "X-Secret: $SECRET" \
  "https://api.alianzacap.com/latest-codes?limit=5"

Related Documentation

• Source: alianza-hq/backend/karibe/email-verification/
• Infrastructure: alianza-infra/modules/karibe/