@private.me/xbind 1.3.5 → 3.0.0

package/dist-standalone/email-transport.js

@@ -1,232 +1 @@
-/**
- * @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();
-    }
-}
+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()}}

package/dist-standalone/envelope.d.ts

@@ -227,9 +227,37 @@ export interface CreateSignedEnvelopeOptions {
 /** Envelope error codes. */
 export type EnvelopeError = 'INVALID_VERSION' | 'INVALID_ALG' | 'INVALID_KEM' | 'INVALID_DID' | 'INVALID_NONCE' | 'INVALID_FIELDS' | 'ENCRYPT_FAILED' | 'DECRYPT_FAILED' | 'SIGN_FAILED' | 'PQ_SIGN_FAILED' | 'VERIFY_FAILED' | 'PARSE_FAILED';
 /**
- * Create a signed, encrypted TransportEnvelope.
+ * Create a signed, encrypted TransportEnvelope (version 1).
  *
  * Encrypt-then-sign: AES-256-GCM encrypts payload, Ed25519 signs ciphertext.
+ * All envelope metadata (nonce, timestamp, sender, recipient, scope) is included
+ * in the signature to prevent replay attacks.
+ *
+ * @param opts - Envelope creation options
+ * @returns Result containing the envelope or error
+ *
+ * @example
+ * ```typescript
+ * import { createEnvelope, generateSharedKey } from '@private.me/xbind';
+ *
+ * // Generate shared key (typically from ECDH key agreement)
+ * const sharedKey = await generateSharedKey(senderDid, recipientDid);
+ * if (!sharedKey.ok) throw new Error(sharedKey.error);
+ *
+ * // Create encrypted envelope
+ * const envelope = await createEnvelope({
+ *   sender: 'did:key:z6Mk...',
+ *   recipient: 'did:key:z6Mk...',
+ *   plaintext: new TextEncoder().encode(JSON.stringify({ message: 'Hello' })),
+ *   sharedKey: sharedKey.value,
+ *   privateKey: senderPrivateKey,
+ *   scope: 'read:messages'
+ * });
+ *
+ * if (envelope.ok) {
+ *   console.log('Envelope created:', envelope.value);
+ * }
+ * ```
  */
 export declare function createEnvelope(opts: CreateEnvelopeOptions): Promise<Result<TransportEnvelope, EnvelopeError>>;
 /**