@private.me/xbind 3.0.0 → 3.0.2

package/dist-standalone/email-transport.js

@@ -1 +1,232 @@
-import{ok,err}from"./_deps/shared/index.js";import{renderInviteEmail}from"./email-templates.js";import nodemailer from"nodemailer";export class EmailTransport{config;transporter;rateLimits;constructor(t){this.config={...t,rateLimit:t.rateLimit??10,tokenExpiryHours:t.tokenExpiryHours??48},this.transporter=nodemailer.createTransport({host:this.config.smtpHost,port:this.config.smtpPort,secure:!1,auth:{user:this.config.smtpUser,pass:this.config.smtpPass}}),this.rateLimits=new Map}async send(t,e){const{from:r,to:i,payload:s}=t;if(!this.isValidEmail(i))return err("SEND_FAILED");if(!this.checkRateLimit(r).ok)return err("SEND_FAILED");try{const e=await this.generateInviteToken(t),o=`${this.config.acceptBaseUrl}/${e}`,a=renderInviteEmail({agentName:s.agentName||r,did:r,acceptUrl:o,message:s.message});return await this.transporter.sendMail({from:`"${this.config.fromName}" <${this.config.fromEmail}>`,to:i,subject:`${s.agentName||"Agent"} wants to connect`,html:a}),this.incrementRateLimit(r),ok(void 0)}catch(t){return err("NETWORK_ERROR")}}isValidEmail(t){return/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(t)}checkRateLimit(t){const e=Date.now(),r=this.rateLimits.get(t);return r?e>=r.resetAt?(this.rateLimits.delete(t),ok(void 0)):r.count>=this.config.rateLimit?err(void 0):ok(void 0):ok(void 0)}incrementRateLimit(t){const e=Date.now(),r=this.rateLimits.get(t);r?r.count+=1:this.rateLimits.set(t,{count:1,resetAt:e+36e5})}async generateInviteToken(t){const e={from:t.from,publicKey:t.payload.publicKey,endpoint:t.payload.endpoint,timestamp:Date.now(),expiresAt:Date.now()+60*this.config.tokenExpiryHours*60*1e3},r=JSON.stringify(e);return Buffer.from(r).toString("base64").replace(/\+/g,"-").replace(/\//g,"_").replace(/=/g,"")}async verify(){try{return await this.transporter.verify(),ok(void 0)}catch(t){return err("NETWORK_ERROR")}}async close(){this.transporter.close()}onReceive(t){}dispose(){this.transporter.close()}}
+/**
+ * @module email-transport
+ * Email-based transport adapter for xBind agent invitations.
+ *
+ * Enables viral growth through email-based connection discovery:
+ * - Agent A sends email invite to Agent B
+ * - Email contains one-click acceptance link
+ * - Agent B clicks link, connection established
+ * - No manual DID exchange required
+ *
+ * @example
+ * ```ts
+ * import { EmailTransport } from '@private.me/xbind/email-transport';
+ *
+ * const transport = new EmailTransport({
+ *   smtpHost: process.env.SMTP_HOST,
+ *   smtpPort: 587,
+ *   smtpUser: process.env.SMTP_USER,
+ *   smtpPass: process.env.SMTP_PASS,
+ *   fromEmail: 'noreply@private.me',
+ *   acceptBaseUrl: 'https://private.me/xbind/accept'
+ * });
+ *
+ * const agent = await Agent.create({
+ *   name: 'payment-processor',
+ *   transport
+ * });
+ *
+ * await agent.invite({
+ *   to: 'fulfillment@acme.com',
+ *   message: 'Connect our systems'
+ * });
+ * ```
+ */
+import { ok, err } from"./_deps/shared/index.js";
+import { renderInviteEmail } from './email-templates.js';
+import nodemailer from 'nodemailer';
+/**
+ * Email-based transport adapter for xBind invitations.
+ *
+ * Sends invitation emails with branded templates and one-click acceptance links.
+ * Enforces rate limiting and token expiration for security.
+ *
+ * Note: Email transport is one-way (sending only). onReceive() is not supported.
+ */
+export class EmailTransport {
+    config;
+    transporter;
+    rateLimits;
+    /**
+     * Create email transport adapter.
+     *
+     * @param config - SMTP and email configuration
+     */
+    constructor(config) {
+        this.config = {
+            ...config,
+            rateLimit: config.rateLimit ?? 10,
+            tokenExpiryHours: config.tokenExpiryHours ?? 48,
+        };
+        // Create nodemailer transporter
+        this.transporter = nodemailer.createTransport({
+            host: this.config.smtpHost,
+            port: this.config.smtpPort,
+            secure: false, // TLS on port 587
+            auth: {
+                user: this.config.smtpUser,
+                pass: this.config.smtpPass,
+            },
+        });
+        this.rateLimits = new Map();
+    }
+    /**
+     * Send invitation email.
+     *
+     * @param envelope - Transport envelope
+     * @param recipientDid - Recipient DID (email address for email transport)
+     * @returns Result with void on success
+     */
+    async send(envelope, recipientDid) {
+        // Extract invitation data from envelope
+        const { from, to, payload } = envelope;
+        // Validate email address
+        if (!this.isValidEmail(to)) {
+            return err('SEND_FAILED');
+        }
+        // Check rate limit
+        const rateLimitCheck = this.checkRateLimit(from);
+        if (!rateLimitCheck.ok) {
+            return err('SEND_FAILED');
+        }
+        try {
+            // Generate secure invitation token
+            const token = await this.generateInviteToken(envelope);
+            // Construct acceptance URL
+            const acceptUrl = `${this.config.acceptBaseUrl}/${token}`;
+            // Render branded email template
+            const html = renderInviteEmail({
+                agentName: payload.agentName || from,
+                did: from,
+                acceptUrl,
+                message: payload.message,
+            });
+            // Send email via SMTP
+            await this.transporter.sendMail({
+                from: `"${this.config.fromName}" <${this.config.fromEmail}>`,
+                to,
+                subject: `${payload.agentName || 'Agent'} wants to connect`,
+                html,
+            });
+            // Update rate limit counter
+            this.incrementRateLimit(from);
+            return ok(undefined);
+        }
+        catch (error) {
+            return err('NETWORK_ERROR');
+        }
+    }
+    /**
+     * Validate email address format.
+     *
+     * @param email - Email address to validate
+     * @returns True if valid
+     */
+    isValidEmail(email) {
+        const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+        return emailRegex.test(email);
+    }
+    /**
+     * Check if agent has exceeded rate limit.
+     *
+     * @param agentDid - Agent DID
+     * @returns Result indicating if rate limit is OK
+     */
+    checkRateLimit(agentDid) {
+        const now = Date.now();
+        const entry = this.rateLimits.get(agentDid);
+        if (!entry) {
+            return ok(undefined);
+        }
+        // Reset if hour has passed
+        if (now >= entry.resetAt) {
+            this.rateLimits.delete(agentDid);
+            return ok(undefined);
+        }
+        // Check if limit exceeded
+        if (entry.count >= this.config.rateLimit) {
+            return err(undefined);
+        }
+        return ok(undefined);
+    }
+    /**
+     * Increment rate limit counter for agent.
+     *
+     * @param agentDid - Agent DID
+     */
+    incrementRateLimit(agentDid) {
+        const now = Date.now();
+        const entry = this.rateLimits.get(agentDid);
+        if (!entry) {
+            this.rateLimits.set(agentDid, {
+                count: 1,
+                resetAt: now + (60 * 60 * 1000), // 1 hour
+            });
+        }
+        else {
+            entry.count += 1;
+        }
+    }
+    /**
+     * Generate secure invitation token.
+     *
+     * Token contains: sender DID, sender public key, timestamp, expiry.
+     * Encoded as base64url for URL safety.
+     *
+     * @param envelope - Message envelope
+     * @returns Invitation token
+     */
+    async generateInviteToken(envelope) {
+        const tokenData = {
+            from: envelope.from,
+            publicKey: envelope.payload.publicKey,
+            endpoint: envelope.payload.endpoint,
+            timestamp: Date.now(),
+            expiresAt: Date.now() + (this.config.tokenExpiryHours * 60 * 60 * 1000),
+        };
+        // Encode as base64url
+        const json = JSON.stringify(tokenData);
+        const base64 = Buffer.from(json).toString('base64')
+            .replace(/\+/g, '-')
+            .replace(/\//g, '_')
+            .replace(/=/g, '');
+        return base64;
+    }
+    /**
+     * Verify connection to SMTP server.
+     *
+     * @returns Result indicating if SMTP connection is OK
+     */
+    async verify() {
+        try {
+            await this.transporter.verify();
+            return ok(undefined);
+        }
+        catch (error) {
+            return err('NETWORK_ERROR');
+        }
+    }
+    /**
+     * Close SMTP connection.
+     */
+    async close() {
+        this.transporter.close();
+    }
+    /**
+     * Register handler for incoming envelopes.
+     *
+     * Note: Email transport is one-way (sending only).
+     * This method exists for interface compliance but is a no-op.
+     *
+     * @param handler - Envelope handler (unused)
+     */
+    onReceive(handler) {
+        // Email transport is one-way - no incoming messages
+    }
+    /**
+     * Shut down the transport (close SMTP connection).
+     */
+    dispose() {
+        this.transporter.close();
+    }
+}