v0.3.1 — The Locksmith Update (#73)

* refactor: extract shared IMAP package, consolidate duplicated dial/search logic

Closes #37, closes #38

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix: use slog.Warn instead of log.Printf in email/delete

Closes #39

* fix: match Peek field in FindBodySection calls to fetch options

FindBodySection uses exact struct comparison. The fetch used Peek: true but
the lookup used the default Peek: false, causing a mismatch on multipart
messages.

Closes #40

* security: enforce TLS for SMTP in email/send connector

Replace smtp.SendMail (which silently falls back to plaintext) with
explicit TLS: port 465 uses implicit TLS, all other ports use STARTTLS
and fail if the server does not support it.

Closes #34

* security: add tmpfs /tmp mount to Docker containers

Adds a tmpfs mount for /tmp with noexec,nosuid flags. ReadOnlyRootfs is
not enabled by default as it breaks browser/run containers that need
npm/pip install.

Closes #41

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* docs: add AdvanceExecution godoc caveat for hot-reload behavior

Closes #43

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* docs: document TypeScript limitations in browser/run connector

Closes #42

* docs: document browser/run script field trust boundary

Closes #35

* docs: document error message infrastructure leakage risk

Closes #44

* docs: document TLS enforcement for email/send connector

* chore: remove npm wrapper references

Closes #72

* fix: address CodeRabbit review findings

- Add /tmp to blockedMountTargets to prevent user mount conflicts with tmpfs
- Use context-aware dialing (DialContext) in SMTP connector for timeout respect
- Fix markdown blank line before closing admonition fence

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* ci: upgrade site build to Node 24

The runner's default Node 20 is no longer supported. Add explicit
setup-node step with Node 24 before setup-bun.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* ci: remove site build workflow

Site deploys via Cloudflare Workers directly. The CI build step is
redundant. Will re-add with lint/test jobs when those are configured.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix: update examples page path for monorepo structure

The examples directory moved from root examples/ to
packages/site/src/content/examples/ during the monorepo conversion.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix: address PR review feedback

- Validate username/password in ParseCredentialMap for early, clear errors
- Fix FindBodySection Peek mismatch in email_receive.go messageBufferToMap
  (same class of bug as #40, propagate Peek value from fetch options)

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix: use process.cwd() for examples path in site build

import.meta.url resolves relative to the built output directory during
Astro's static build, not the source tree. Use process.cwd() which
is always packages/site/ during build.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: michaelmcnees

.github/workflows/site-ci.yml

@@ -146,7 +146,6 @@ Every additional installation method removes friction. Prioritize by audience ov
 | Helm chart | P0 (done) | None | K8s is the deployment target |
 | Binary releases (GitHub Releases) | P0 | Low | goreleaser config, covers Linux/macOS/Windows |
 | Homebrew tap | P1 | Low | macOS developers, easy to maintain a tap |
-| npm wrapper | P2 | Low | Enables `npx mantle` for polyglot teams |
 | Nix package | P3 | Medium | Nix users are vocal advocates, good word-of-mouth |
 | AUR (Arch Linux) | P3 | Low | Small but passionate community |
 

go.work.sum

@@ -23,7 +23,7 @@ import (
 )
 
 // blockedMountTargets lists container paths that are never allowed as mount targets.
-var blockedMountTargets = []string{"/proc", "/sys", "/dev", "/var/run/docker.sock"}
+var blockedMountTargets = []string{"/proc", "/sys", "/dev", "/var/run/docker.sock", "/tmp"}
 
 // DockerRunConnector runs a container to completion and captures output.
 type DockerRunConnector struct{}
@@ -294,6 +294,9 @@ func (c *DockerRunConnector) Execute(ctx context.Context, params map[string]any)
 		NetworkMode: container.NetworkMode(cfg.Network),
 		CapDrop:     []string{"ALL"},
 		SecurityOpt: []string{"no-new-privileges"},
+		Tmpfs: map[string]string{
+			"/tmp": "rw,noexec,nosuid,size=256m",
+		},
 		Resources: container.Resources{
 			PidsLimit: int64Ptr(512),
 		},

marketing/growth-strategy.md

@@ -2,6 +2,7 @@ package connector
 
 import (
 	"context"
+	"crypto/tls"
 	"fmt"
 	"net"
 	"net/smtp"
@@ -63,14 +64,80 @@ func (c *EmailSendConnector) Execute(ctx context.Context, params map[string]any)
 	msg := buildMessage(from, recipients, subject, body, isHTML)
 
 	addr := net.JoinHostPort(host, port)
+	tlsCfg := &tls.Config{ServerName: host} //nolint:gosec // MinVersion not set; Go's default is TLS 1.2+
+	dialer := &net.Dialer{}
+
+	var client *smtp.Client
+
+	if port == "465" {
+		// Implicit TLS (SMTPS): dial with TLS directly, respecting context deadline.
+		conn, dialErr := dialer.DialContext(ctx, "tcp", addr)
+		if dialErr != nil {
+			return nil, fmt.Errorf("email/send: dial %s: %w", addr, dialErr)
+		}
+		tlsConn := tls.Client(conn, tlsCfg)
+		if err := tlsConn.HandshakeContext(ctx); err != nil {
+			_ = conn.Close()
+			return nil, fmt.Errorf("email/send: TLS handshake with %s: %w", addr, err)
+		}
+		c, newErr := smtp.NewClient(tlsConn, host)
+		if newErr != nil {
+			_ = tlsConn.Close()
+			return nil, fmt.Errorf("email/send: SMTP handshake: %w", newErr)
+		}
+		client = c
+	} else {
+		// Explicit TLS (STARTTLS): connect plaintext, then upgrade.
+		conn, dialErr := dialer.DialContext(ctx, "tcp", addr)
+		if dialErr != nil {
+			return nil, fmt.Errorf("email/send: dial %s: %w", addr, dialErr)
+		}
+		c, newErr := smtp.NewClient(conn, host)
+		if newErr != nil {
+			_ = conn.Close()
+			return nil, fmt.Errorf("email/send: SMTP handshake: %w", newErr)
+		}
+		ok, _ := c.Extension("STARTTLS")
+		if !ok {
+			_ = c.Close()
+			return nil, fmt.Errorf("email/send: server %s does not support STARTTLS; refusing to send credentials in plaintext", host)
+		}
+		if startErr := c.StartTLS(tlsCfg); startErr != nil {
+			_ = c.Close()
+			return nil, fmt.Errorf("email/send: STARTTLS negotiation with %s: %w", host, startErr)
+		}
+		client = c
+	}
+	defer client.Close() //nolint:errcheck
 
-	var auth smtp.Auth
 	if username != "" {
-		auth = smtp.PlainAuth("", username, password, host)
+		auth := smtp.PlainAuth("", username, password, host)
+		if authErr := client.Auth(auth); authErr != nil {
+			return nil, fmt.Errorf("email/send: SMTP auth: %w", authErr)
+		}
 	}
 
-	if err := smtp.SendMail(addr, auth, from, recipients, msg); err != nil {
-		return nil, fmt.Errorf("email/send: %w", err)
+	if err := client.Mail(from); err != nil {
+		return nil, fmt.Errorf("email/send: MAIL FROM: %w", err)
+	}
+	for _, rcpt := range recipients {
+		if err := client.Rcpt(rcpt); err != nil {
+			return nil, fmt.Errorf("email/send: RCPT TO <%s>: %w", rcpt, err)
+		}
+	}
+	wc, err := client.Data()
+	if err != nil {
+		return nil, fmt.Errorf("email/send: DATA command: %w", err)
+	}
+	if _, err = wc.Write(msg); err != nil {
+		_ = wc.Close()
+		return nil, fmt.Errorf("email/send: writing message body: %w", err)
+	}
+	if err = wc.Close(); err != nil {
+		return nil, fmt.Errorf("email/send: closing DATA writer: %w", err)
+	}
+	if err = client.Quit(); err != nil {
+		return nil, fmt.Errorf("email/send: QUIT: %w", err)
 	}
 
 	return map[string]any{

packages/engine/internal/connector/docker.go

@@ -3,7 +3,7 @@ package connector
 import (
 	"context"
 	"fmt"
-	"log"
+	"log/slog"
 
 	"github.com/emersion/go-imap/v2"
 )
@@ -60,7 +60,10 @@ func (c *EmailDeleteConnector) Execute(ctx context.Context, params map[string]an
 		// Warning: EXPUNGE removes ALL messages currently marked \Deleted in the
 		// selected mailbox, not just the targeted UID. This may delete additional
 		// messages if other messages were marked \Deleted concurrently.
-		log.Printf("email/delete: UIDExpunge not supported (uid=%d), falling back to EXPUNGE which removes ALL \\Deleted messages: %v", uid, err)
+		slog.Warn("email/delete: UIDExpunge not supported, falling back to EXPUNGE which removes ALL \\Deleted messages",
+			"uid", uid,
+			"error", err,
+		)
 		if err2 := client.Expunge().Close(); err2 != nil {
 			return nil, fmt.Errorf("email/delete: expunging message: %w", err2)
 		}

packages/engine/internal/connector/email.go

@@ -6,6 +6,8 @@ import (
 	"net/smtp"
 	"testing"
 	"time"
+
+	imaplib "github.com/dvflw/mantle/internal/imap"
 )
 
 // TestEmailMoveParamValidation verifies that required parameters are enforced.
@@ -131,7 +133,7 @@ func TestEmailMove_MovesMessage(t *testing.T) {
 // Used in tests to ensure the target folder exists before moving messages.
 func createTargetFolder(t *testing.T, host, imapPort, username, password, folder string) {
 	t.Helper()
-	cfg := &imapConfig{
+	cfg := &imaplib.Config{
 		Host:     host,
 		Port:     imapPort,
 		Username: username,

packages/engine/internal/connector/email_delete.go

@@ -9,6 +9,7 @@ import (
 	"strings"
 	"time"
 
+	imaplib "github.com/dvflw/mantle/internal/imap"
 	"github.com/emersion/go-imap/v2"
 	"github.com/emersion/go-imap/v2/imapclient"
 )
@@ -74,7 +75,7 @@ func (c *EmailReceiveConnector) Execute(ctx context.Context, params map[string]a
 	}
 
 	// Build search criteria based on the filter.
-	criteria := buildSearchCriteria(filter)
+	criteria := imaplib.BuildSearchCriteria(filter)
 
 	// Use UID search so we can build a UIDSet for Fetch.
 	searchData, err := client.UIDSearch(criteria, nil).Wait()
@@ -115,7 +116,7 @@ func (c *EmailReceiveConnector) Execute(ctx context.Context, params map[string]a
 		},
 	}
 
-	messages, err := fetchMessages(client, uidSet, fetchOptions)
+	messages, err := fetchMessages(client, uidSet, fetchOptions, !markSeen)
 	if err != nil {
 		return nil, fmt.Errorf("email/receive: fetch failed: %w", err)
 	}
@@ -140,30 +141,9 @@ func (c *EmailReceiveConnector) Execute(ctx context.Context, params map[string]a
 	}, nil
 }
 
-// buildSearchCriteria constructs IMAP search criteria for the given filter name.
-func buildSearchCriteria(filter string) *imap.SearchCriteria {
-	switch filter {
-	case "unseen":
-		return &imap.SearchCriteria{
-			NotFlag: []imap.Flag{imap.FlagSeen},
-		}
-	case "flagged":
-		return &imap.SearchCriteria{
-			Flag: []imap.Flag{imap.FlagFlagged},
-		}
-	case "recent":
-		// \Recent is an IMAP4rev1 flag; use string literal.
-		return &imap.SearchCriteria{
-			Flag: []imap.Flag{imap.Flag(`\Recent`)},
-		}
-	default: // "all"
-		return &imap.SearchCriteria{}
-	}
-}
-
 // fetchMessages executes the FETCH command and converts the results into the
 // output map format expected by the connector.
-func fetchMessages(client *imapclient.Client, uidSet imap.UIDSet, opts *imap.FetchOptions) ([]map[string]any, error) {
+func fetchMessages(client *imapclient.Client, uidSet imap.UIDSet, opts *imap.FetchOptions, peek bool) ([]map[string]any, error) {
 	cmd := client.Fetch(uidSet, opts)
 
 	var out []map[string]any
@@ -179,7 +159,7 @@ func fetchMessages(client *imapclient.Client, uidSet imap.UIDSet, opts *imap.Fet
 			return nil, err
 		}
 
-		msg := messageBufferToMap(buf)
+		msg := messageBufferToMap(buf, peek)
 		out = append(out, msg)
 	}
 
@@ -191,7 +171,9 @@ func fetchMessages(client *imapclient.Client, uidSet imap.UIDSet, opts *imap.Fet
 }
 
 // messageBufferToMap converts a FetchMessageBuffer into the output map format.
-func messageBufferToMap(buf *imapclient.FetchMessageBuffer) map[string]any {
+// peek must match the Peek value used in the FetchItemBodySection so that
+// FindBodySection can locate the correct section by exact struct comparison.
+func messageBufferToMap(buf *imapclient.FetchMessageBuffer, peek bool) map[string]any {
 	msg := map[string]any{
 		"message_id": "",
 		"from":       "",
@@ -230,7 +212,7 @@ func messageBufferToMap(buf *imapclient.FetchMessageBuffer) map[string]any {
 
 	// Populate body text from the TEXT body section, and extract headers from
 	// the raw bytes if a full body section is present.
-	bodySection := &imap.FetchItemBodySection{Specifier: imap.PartSpecifierText}
+	bodySection := &imap.FetchItemBodySection{Specifier: imap.PartSpecifierText, Peek: peek}
 	rawText := buf.FindBodySection(bodySection)
 	if rawText != nil {
 		msg["body"] = extractBodyText(rawText)

packages/engine/internal/connector/email_move_test.go

@@ -8,6 +8,7 @@ import (
 	"testing"
 	"time"
 
+	imaplib "github.com/dvflw/mantle/internal/imap"
 	"github.com/testcontainers/testcontainers-go"
 	"github.com/testcontainers/testcontainers-go/wait"
 )
@@ -90,7 +91,7 @@ func TestEmailReceiveFilterCriteria(t *testing.T) {
 
 	for _, tt := range tests {
 		t.Run(tt.filter, func(t *testing.T) {
-			c := buildSearchCriteria(tt.filter)
+			c := imaplib.BuildSearchCriteria(tt.filter)
 			if c == nil {
 				t.Fatal("buildSearchCriteria returned nil")
 			}

packages/engine/internal/connector/email_receive.go

@@ -1,69 +1,18 @@
 package connector
 
 import (
-	"crypto/tls"
-	"fmt"
-	"net"
-
+	imaplib "github.com/dvflw/mantle/internal/imap"
 	"github.com/emersion/go-imap/v2/imapclient"
 )
 
-// imapConfig holds IMAP connection parameters extracted from a credential.
-type imapConfig struct {
-	Host     string
-	Port     string
-	Username string
-	Password string
-	UseTLS   bool
-}
-
-// parseIMAPCredential extracts IMAP config from a credential map.
-func parseIMAPCredential(params map[string]any) (*imapConfig, error) {
-	cred, ok := params["_credential"].(map[string]string)
-	if !ok {
-		return nil, fmt.Errorf("IMAP credential is required")
-	}
-	cfg := &imapConfig{
-		Host:     cred["host"],
-		Port:     cred["port"],
-		Username: cred["username"],
-		Password: cred["password"],
-	}
-	if cfg.Host == "" {
-		return nil, fmt.Errorf("IMAP credential must include 'host'")
-	}
-	if cfg.Port == "" {
-		cfg.Port = "993"
-	}
-	if useTLS, ok := cred["use_tls"]; ok && useTLS == "false" {
-		cfg.UseTLS = false
-	} else {
-		cfg.UseTLS = true
-	}
-	return cfg, nil
+// parseIMAPCredential extracts IMAP config from connector params.
+// It delegates to the shared imap package.
+func parseIMAPCredential(params map[string]any) (*imaplib.Config, error) {
+	return imaplib.ParseCredential(params)
 }
 
 // imapDial connects to an IMAP server and logs in.
-func imapDial(cfg *imapConfig) (*imapclient.Client, error) {
-	addr := net.JoinHostPort(cfg.Host, cfg.Port)
-	var client *imapclient.Client
-	var err error
-	if cfg.UseTLS {
-		client, err = imapclient.DialTLS(addr, &imapclient.Options{
-			TLSConfig: &tls.Config{
-				ServerName: cfg.Host,
-				MinVersion: tls.VersionTLS12,
-			},
-		})
-	} else {
-		client, err = imapclient.DialInsecure(addr, nil)
-	}
-	if err != nil {
-		return nil, fmt.Errorf("connecting to IMAP server %s: %w", addr, err)
-	}
-	if err := client.Login(cfg.Username, cfg.Password).Wait(); err != nil {
-		_ = client.Close()
-		return nil, fmt.Errorf("IMAP login failed: %w", err)
-	}
-	return client, nil
+// It delegates to the shared imap package.
+func imapDial(cfg *imaplib.Config) (*imapclient.Client, error) {
+	return imaplib.Dial(cfg)
 }