Sail JADA — Engineering Log

Technical work on sailjada.com and the JADA booking systems

```html

Implementing Credential Management and Twilio Integration for Multi-Tenant SMS Routing

This session addressed a critical infrastructure gap: establishing secure credential storage and building the foundation for Twilio-based SMS relay functionality across distributed contact workflows. The work bridges gaps in our multi-tenant architecture where carrier-level call forwarding proved insufficient for cascading communication paths.

What Was Done

  • Established secure credential storage in /Users/cb/Documents/repos/.secrets/repos.env with restrictive file permissions (mode 600)
  • Created reference documentation linking credential types to their operational purpose
  • Updated project memory systems to track credential ownership and integration pathways
  • Identified architectural requirements for Twilio relay implementation in the Queen of San Diego domain (QDN) cascading forward workflow

Technical Details: Credential Architecture

The credential intake revealed two distinct Twilio credential types serving different operational roles:

Account-Level Authentication (Account SID + Auth Token)

The TWILIO_ACCOUNT_SID and TWILIO_AUTH_TOKEN pair provide administrative access to the Twilio account. These are appended to repos.env and serve use cases requiring account-wide operations: provisioning phone numbers, modifying account settings, and accessing comprehensive billing/usage APIs. The auth token grants broad permissions and should be rotated regularly.

Storage location: /Users/cb/Documents/repos/.secrets/repos.env

Permission model: File-level access control (mode 600) restricts reading to the account owner; no group or world readability.

API Key Credentials (API Key + Secret)

The "Main" API key and corresponding secret provide scoped, rotatable credentials suitable for SDK runtime operations. These credentials support message sending, call initiation, and webhook verification without requiring full account access. API keys can be revoked independently without affecting the master account authentication, making them preferable for deployed services.

Operational advantage: SDK runtimes and CI/CD pipelines should consume API key credentials, not account tokens. This containment model reduces blast radius if a key leaks.

Infrastructure: Credential Storage Patterns

Rather than embedding credentials in version control or environment files committed to git, we implement a three-tier credential isolation strategy:

  • Tier 1 (Local secrets): /Users/cb/Documents/repos/.secrets/repos.env — filesystem-protected, never committed. Referenced by local development and CI tooling via absolute path or symlink.
  • Tier 2 (Runtime injection): Google Apps Script and deployed services read from repos.env` via native secret management (e.g., GAS Properties Service for scoped key storage).
  • Tier 3 (Audit trail): Memory reference documents (stored in /Users/cb/.claude/projects/.../memory/reference_twilio_credentials.md) document credential ownership and integration points without exposing actual secrets.

This pattern prevents accidental exposure while maintaining traceability for future session context.

Architectural Decision: Why Twilio for QDN Cascading Forward

Queen of San Diego's contact forwarding workflow previously relied on carrier-level call forwarding: incoming calls to the main line would forward through Sergio's primary number, then to a backup (858-335-4807) if unreachable. However, carrier-level forwarding has operational limits:

  • No visibility into which tier (primary vs. backup) answered or why
  • No ability to customize routing based on time-of-day, call source, or contact type
  • Inability to log or audit forwarding events for compliance or troubleshooting

Twilio enables an application-layer relay: inbound calls hit a Twilio phone number, then our logic determines routing (primary, backup, voicemail, SMS escalation). This unlocks:

  • Conditional routing: Business hours → Sergio; after-hours → voicemail with SMS callback option
  • Multi-channel fallback: Call fails, trigger SMS to primary + backup simultaneously
  • Event logging: Every call and routing decision is captured in the Twilio API, enabling analytics and post-mortems
  • IVR capabilities: Route based on caller ID or DTMF input (e.g., "press 1 for reservations, 2 for events")

Key Implementation Decisions

Credential Scoping Strategy

We chose to store both account and API-key credentials locally but document preferred usage:

  • Admin scripts and account provisioning: Use TWILIO_ACCOUNT_SID + TWILIO_AUTH_TOKEN
  • Message sending and call initiation in deployed services: Use API key + secret (scoped, rotatable)

This ensures production runtimes never hold account-level credentials, reducing risk if a service is compromised.

Filesystem Permissions and CI/CD Integration

The repos.env file is set to mode 600 (user read/write only). For CI/CD systems that need access:

  • Load secrets from repos.env into environment variables at job start
  • Never log or echo these variables in CI output
  • Rotate credentials annually or after personnel changes

What's Next

With credentials secured, the next phase is scaffolding the Twilio relay implementation:

  • Twilio phone number provisioning: Acquire a dedicated inbound number for QDN; configure to POST incoming call metadata to our webhook endpoint
  • Webhook handler: Deploy a Google Cloud Function or similar that receives Twilio call events, queries business rules (time-of-day, contact type), and returns TwiML routing instructions
  • Routing logic: Implement conditional forwarding: during business hours forward to Sergio's primary; after hours forward to voicemail; on no-answer escalate to SMS backup cascade
  • Audit logging: Write call metadata (timestamp, caller ID, routing decision, outcome) to a Firestore collection for compliance and analytics
  • Testing: Build E2E tests that simulate inbound calls, verify correct routing, and validate TwiML response generation

The credential foundation is now in place; the relay build earns priority because it unblocks QDN's contact workflow bottleneck and provides reusable patterns for other domains (Rady Shell, ShipCaptainCrew) needing intelligent call distribution.

```