handle resolver

bundle/manager.go

···
 	"path/filepath"
 	"runtime"
 	"sort"
+	"strings"
 	"sync"
 	"time"
 
 	"tangled.org/atscan.net/plcbundle/internal/bundleindex"
 	"tangled.org/atscan.net/plcbundle/internal/didindex"
+	"tangled.org/atscan.net/plcbundle/internal/handleresolver"
 	"tangled.org/atscan.net/plcbundle/internal/mempool"
 	"tangled.org/atscan.net/plcbundle/internal/plcclient"
 	"tangled.org/atscan.net/plcbundle/internal/storage"
···
 	operations *storage.Operations
 	index      *bundleindex.Index
 	indexPath  string
-	plcClient  *plcclient.Client
 	logger     types.Logger
 	mempool    *mempool.Mempool
 	didIndex   *didindex.Manager
+
+	plcClient      *plcclient.Client
+	handleResolver *handleresolver.Client
 
 	syncer *internalsync.Fetcher
 	cloner *internalsync.Cloner
···
 	fetcher := internalsync.NewFetcher(plcClient, ops, config.Logger)
 	cloner := internalsync.NewCloner(ops, config.BundleDir, config.Logger)
 
+	// Initialize handle resolver if configured
+	var handleResolver *handleresolver.Client
+	if config.HandleResolverURL != "" {
+		handleResolver = handleresolver.NewClient(config.HandleResolverURL)
+		config.Logger.Printf("Handle resolver configured: %s", config.HandleResolverURL)
+	}
+
 	return &Manager{
-		config:       config,
-		operations:   ops,
-		index:        index,
-		indexPath:    indexPath,
-		plcClient:    plcClient,
-		logger:       config.Logger,
-		mempool:      mempool,
-		didIndex:     didIndex, // Updated type
-		bundleCache:  make(map[int]*Bundle),
-		maxCacheSize: 10,
-		syncer:       fetcher,
-		cloner:       cloner,
+		config:         config,
+		operations:     ops,
+		index:          index,
+		indexPath:      indexPath,
+		logger:         config.Logger,
+		mempool:        mempool,
+		didIndex:       didIndex, // Updated type
+		bundleCache:    make(map[int]*Bundle),
+		maxCacheSize:   10,
+		syncer:         fetcher,
+		cloner:         cloner,
+		plcClient:      plcClient,
+		handleResolver: handleResolver,
 	}, nil
 }
 
···
 
 	return len(bundleFiles) > 0
 }
+
+// ResolveHandleOrDID resolves input that can be either a handle or DID
+// Returns: (did, handleResolveTime, error)
+func (m *Manager) ResolveHandleOrDID(ctx context.Context, input string) (string, time.Duration, error) {
+	input = strings.TrimSpace(input)
+
+	// Normalize handle format (remove at://, @ prefixes)
+	if !strings.HasPrefix(input, "did:") {
+		input = strings.TrimPrefix(input, "at://")
+		input = strings.TrimPrefix(input, "@")
+	}
+
+	// If already a DID, validate and return
+	if strings.HasPrefix(input, "did:plc:") {
+		if err := plcclient.ValidateDIDFormat(input); err != nil {
+			return "", 0, err
+		}
+		return input, 0, nil // ✅ No resolution needed
+	}
+
+	// Support did:web too
+	if strings.HasPrefix(input, "did:web:") {
+		return input, 0, nil
+	}
+
+	// It's a handle - need resolver
+	if m.handleResolver == nil {
+		return "", 0, fmt.Errorf(
+			"input '%s' appears to be a handle, but handle resolver is not configured\n\n"+
+				"Configure resolver with:\n"+
+				"  plcbundle --handle-resolver https://quickdid.smokesignal.tools did resolve %s\n\n"+
+				"Or set default in config",
+			input, input)
+	}
+
+	// ✨ TIME THE RESOLUTION
+	resolveStart := time.Now()
+	m.logger.Printf("Resolving handle: %s", input)
+	did, err := m.handleResolver.ResolveHandle(ctx, input)
+	resolveTime := time.Since(resolveStart)
+
+	if err != nil {
+		return "", resolveTime, fmt.Errorf("failed to resolve handle '%s': %w", input, err)
+	}
+
+	m.logger.Printf("Resolved: %s → %s (in %s)", input, did, resolveTime)
+	return did, resolveTime, nil
+}
+
+// GetHandleResolver returns the handle resolver (can be nil)
+func (m *Manager) GetHandleResolver() *handleresolver.Client {
+	return m.handleResolver
+}

bundle/types.go

···
 
 // Config holds configuration for bundle operations
 type Config struct {
-	BundleDir       string
-	VerifyOnLoad    bool
-	AutoRebuild     bool
-	AutoInit        bool                     // Allow auto-creating empty repository
-	RebuildWorkers  int                      // Number of workers for parallel rebuild (0 = auto-detect)
-	RebuildProgress func(current, total int) // Progress callback for rebuild
-	Logger          types.Logger
+	BundleDir         string
+	HandleResolverURL string
+	VerifyOnLoad      bool
+	AutoRebuild       bool
+	AutoInit          bool                     // Allow auto-creating empty repository
+	RebuildWorkers    int                      // Number of workers for parallel rebuild (0 = auto-detect)
+	RebuildProgress   func(current, total int) // Progress callback for rebuild
+	Logger            types.Logger
 }
 
 // DefaultConfig returns default configuration
 func DefaultConfig(bundleDir string) *Config {
 	return &Config{
-		BundleDir:       bundleDir,
-		VerifyOnLoad:    true,
-		AutoRebuild:     true,
-		AutoInit:        false,
-		RebuildWorkers:  0,   // 0 means auto-detect CPU count
-		RebuildProgress: nil, // No progress callback by default
-		Logger:          nil,
+		BundleDir:         bundleDir,
+		HandleResolverURL: "https://quickdid.atscan.net",
+		VerifyOnLoad:      true,
+		AutoRebuild:       true,
+		AutoInit:          false,
+		RebuildWorkers:    0,   // 0 means auto-detect CPU count
+		RebuildProgress:   nil, // No progress callback by default
+		Logger:            nil,
 	}
 }
 
···
 
 // ResolveDIDResult contains DID resolution with timing metrics
 type ResolveDIDResult struct {
-	Document     *plcclient.DIDDocument
-	MempoolTime  time.Duration
-	IndexTime    time.Duration
-	LoadOpTime   time.Duration
-	TotalTime    time.Duration
-	Source       string // "mempool" or "bundle"
-	BundleNumber int    // if from bundle
-	Position     int    // if from bundle
+	Document       *plcclient.DIDDocument
+	MempoolTime    time.Duration
+	IndexTime      time.Duration
+	LoadOpTime     time.Duration
+	TotalTime      time.Duration
+	ResolvedHandle string
+	Source         string // "mempool" or "bundle"
+	BundleNumber   int    // if from bundle
+	Position       int    // if from bundle
 }

cmd/plcbundle/commands/common.go

···
 	GetBundleIndex() didindex.BundleIndexProvider
 	ScanDirectoryParallel(workers int, progressCallback func(current, total int, bytesProcessed int64)) (*bundle.DirectoryScanResult, error)
 	LoadBundleForDIDIndex(ctx context.Context, bundleNumber int) (*didindex.BundleData, error)
+	ResolveHandleOrDID(ctx context.Context, input string) (string, time.Duration, error)
 }
 
 // PLCOperationWithLocation wraps operation with location info
···
 
 // ManagerOptions configures manager creation
 type ManagerOptions struct {
-	Cmd      *cobra.Command // Optional: for reading --dir flag
-	Dir      string         // Optional: explicit directory (overrides Cmd flag and cwd)
-	PLCURL   string         // Optional: PLC directory URL
-	AutoInit bool           // Optional: allow creating new empty repository (default: false)
+	Cmd               *cobra.Command // Optional: for reading --dir flag
+	Dir               string         // Optional: explicit directory (overrides Cmd flag and cwd)
+	PLCURL            string         // Optional: PLC directory URL
+	HandleResolverURL string         // Optional: Handle resolver URL (XRPC)
+	AutoInit          bool           // Optional: allow creating new empty repository (default: false)
 }
 
 // ============================================================================
···
 	var client *plcclient.Client
 	if opts.PLCURL != "" {
 		client = plcclient.NewClient(opts.PLCURL)
+	}
+
+	// Set handle resolver URL from flag or option
+	handleResolverURL := opts.HandleResolverURL
+	if handleResolverURL == "" && opts.Cmd != nil {
+		handleResolverURL, _ = opts.Cmd.Root().PersistentFlags().GetString("handle-resolver") // ✅ Fixed flag name
+	}
+	// Only override default if explicitly provided
+	if handleResolverURL != "" {
+		config.HandleResolverURL = handleResolverURL
 	}
 
 	// Create manager

cmd/plcbundle/commands/did.go

···
 	)
 
 	cmd := &cobra.Command{
-		Use:     "lookup <did>",
+		Use:     "lookup <did|handle>",
 		Aliases: []string{"find", "get"},
-		Short:   "Find all operations for a DID",
-		Long: `Find all operations for a DID
+		Short:   "Find all operations for a DID or handle",
+		Long: `Find all operations for a DID or handle
 
-Retrieves all operations (both bundled and mempool) for a specific DID,
-showing bundle locations, timestamps, and nullification status.
+Retrieves all operations (both bundled and mempool) for a specific DID.
+Accepts either:
+  • DID: did:plc:524tuhdhh3m7li5gycdn6boe
+  • Handle: tree.fail (resolves via configured resolver)
 
 Requires DID index to be built. If not available, will fall back to
 full scan (slow).`,
 
-		Example: `  # Lookup DID operations
+		Example: `  # Lookup by DID
   plcbundle did lookup did:plc:524tuhdhh3m7li5gycdn6boe
 
-  # Verbose output with timing
-  plcbundle did lookup did:plc:524tuhdhh3m7li5gycdn6boe -v
+  # Lookup by handle (requires --resolver-url)
+  plcbundle did lookup tree.fail
+  plcbundle did lookup ngerakines.me
 
-  # JSON output
-  plcbundle did lookup did:plc:524tuhdhh3m7li5gycdn6boe --json
-
-  # Using alias
-  plcbundle did find did:plc:524tuhdhh3m7li5gycdn6boe`,
+  # With non-default handle resolver configured
+  plcbundle --handle-resolver https://quickdid.smokesignal.tools did lookup tree.fail`,
 
 		Args: cobra.ExactArgs(1),
 
 		RunE: func(cmd *cobra.Command, args []string) error {
-			did := args[0]
+			input := args[0]
 
 			mgr, _, err := getManager(&ManagerOptions{Cmd: cmd})
 			if err != nil {
···
 			}
 			defer mgr.Close()
 
+			// ✨ Resolve handle to DID with timing
+			ctx := context.Background()
+			did, handleResolveTime, err := mgr.ResolveHandleOrDID(ctx, input)
+			if err != nil {
+				return err
+			}
+
+			// Show what we resolved to (if it was a handle)
+			if input != did && !showJSON {
+				fmt.Fprintf(os.Stderr, "Resolved handle '%s' → %s (in %s)\n\n",
+					input, did, handleResolveTime)
+			}
+
 			stats := mgr.GetDIDIndexStats()
 			if !stats["exists"].(bool) {
 				fmt.Fprintf(os.Stderr, "⚠️  DID index not found. Run: plcbundle index build\n")
···
 			}
 
 			totalStart := time.Now()
-			ctx := context.Background()
 
 			// Lookup operations
 			lookupStart := time.Now()
···
   plcbundle did resolve did:plc:524tuhdhh3m7li5gycdn6boe --raw
 
   # Pipe to jq
-  plcbundle did resolve did:plc:524tuhdhh3m7li5gycdn6boe | jq .service`,
+  plcbundle did resolve did:plc:524tuhdhh3m7li5gycdn6boe | jq .service
+  
+  # Resolve by handle
+  plcbundle did resolve tree.fail`,
 
 		Args: cobra.ExactArgs(1),
 
 		RunE: func(cmd *cobra.Command, args []string) error {
-			did := args[0]
+			input := args[0]
 
 			mgr, _, err := getManager(&ManagerOptions{Cmd: cmd})
 			if err != nil {
···
 
 			ctx := context.Background()
 
+			// ✨ Resolve handle to DID with timing
+			did, handleResolveTime, err := mgr.ResolveHandleOrDID(ctx, input)
+			if err != nil {
+				return err
+			}
+
+			// Show resolution timing if it was a handle
+			if input != did {
+				if showTiming {
+					fmt.Fprintf(os.Stderr, "Handle resolution: %s → %s (%s)\n",
+						input, did, handleResolveTime)
+				} else {
+					fmt.Fprintf(os.Stderr, "Resolved handle '%s' → %s\n", input, did)
+				}
+			}
+
 			if showTiming {
-				fmt.Fprintf(os.Stderr, "Resolving: %s\n", did)
+				fmt.Fprintf(os.Stderr, "Resolving DID: %s\n", did)
 			}
 
 			if verbose {
···
 
 			// Display timing if requested
 			if showTiming {
+				if handleResolveTime > 0 {
+					fmt.Fprintf(os.Stderr, "Handle: %s | ", handleResolveTime)
+				}
 				if result.Source == "mempool" {
 					fmt.Fprintf(os.Stderr, "Mempool check: %s (✓ found)\n", result.MempoolTime)
 					fmt.Fprintf(os.Stderr, "Total: %s\n\n", result.TotalTime)

cmd/plcbundle/main.go

···
 	cmd.PersistentFlags().StringP("dir", "C", "", "Repository directory (default: current directory)")
 	cmd.PersistentFlags().BoolP("verbose", "v", false, "Show detailed output and progress")
 	cmd.PersistentFlags().BoolP("quiet", "q", false, "Suppress non-error output")
+	cmd.PersistentFlags().String("handle-resolver", "",
+		"Handle resolver URL (e.g., https://quickdid.smokesignal.tools)")
 
 	// Bundle operations (root level - most common)
 	cmd.AddCommand(commands.NewSyncCommand())

internal/handleresolver/resolver.go

···
+package handleresolver
+
+import (
+	"context"
+	"fmt"
+	"io"
+	"net/http"
+	"net/url"
+	"regexp"
+	"strings"
+	"time"
+
+	"github.com/goccy/go-json"
+)
+
+// Client resolves AT Protocol handles to DIDs via XRPC
+type Client struct {
+	baseURL    string
+	httpClient *http.Client
+}
+
+// NewClient creates a new handle resolver client
+func NewClient(baseURL string) *Client {
+	return &Client{
+		baseURL: strings.TrimSuffix(baseURL, "/"),
+		httpClient: &http.Client{
+			Timeout: 10 * time.Second,
+		},
+	}
+}
+
+// ResolveHandle resolves a handle to a DID using com.atproto.identity.resolveHandle
+func (c *Client) ResolveHandle(ctx context.Context, handle string) (string, error) {
+	// Validate handle format
+	if err := ValidateHandleFormat(handle); err != nil {
+		return "", err
+	}
+
+	// Build XRPC URL
+	endpoint := fmt.Sprintf("%s/xrpc/com.atproto.identity.resolveHandle", c.baseURL)
+
+	// Add query parameter
+	params := url.Values{}
+	params.Add("handle", handle)
+	fullURL := fmt.Sprintf("%s?%s", endpoint, params.Encode())
+
+	// Create request
+	req, err := http.NewRequestWithContext(ctx, "GET", fullURL, nil)
+	if err != nil {
+		return "", fmt.Errorf("failed to create request: %w", err)
+	}
+
+	// Execute request
+	resp, err := c.httpClient.Do(req)
+	if err != nil {
+		return "", fmt.Errorf("failed to resolve handle: %w", err)
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode != http.StatusOK {
+		body, _ := io.ReadAll(resp.Body)
+		return "", fmt.Errorf("resolver returned status %d: %s", resp.StatusCode, string(body))
+	}
+
+	// Parse response
+	var result struct {
+		DID string `json:"did"`
+	}
+	if err := json.NewDecoder(resp.Body).Decode(&result); err != nil {
+		return "", fmt.Errorf("failed to parse response: %w", err)
+	}
+
+	if result.DID == "" {
+		return "", fmt.Errorf("resolver returned empty DID")
+	}
+
+	// Validate returned DID
+	if !strings.HasPrefix(result.DID, "did:plc:") && !strings.HasPrefix(result.DID, "did:web:") {
+		return "", fmt.Errorf("invalid DID format returned: %s", result.DID)
+	}
+
+	return result.DID, nil
+}
+
+// ValidateHandleFormat validates AT Protocol handle format
+func ValidateHandleFormat(handle string) error {
+	if handle == "" {
+		return fmt.Errorf("handle cannot be empty")
+	}
+
+	// Handle can't be a DID
+	if strings.HasPrefix(handle, "did:") {
+		return fmt.Errorf("input is already a DID, not a handle")
+	}
+
+	// Basic length check
+	if len(handle) > 253 {
+		return fmt.Errorf("handle too long (max 253 chars)")
+	}
+
+	// Must have at least one dot (domain.tld)
+	if !strings.Contains(handle, ".") {
+		return fmt.Errorf("handle must be a domain (e.g., user.bsky.social)")
+	}
+
+	// Valid handle pattern (simplified - matches AT Protocol spec)
+	validPattern := regexp.MustCompile(`^([a-zA-Z0-9]([a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?\.)+[a-zA-Z]([a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?$`)
+	if !validPattern.MatchString(handle) {
+		return fmt.Errorf("invalid handle format")
+	}
+
+	return nil
+}
+
+// IsHandle checks if a string looks like a handle (not a DID)
+func IsHandle(input string) bool {
+	return !strings.HasPrefix(input, "did:")
+}
+
+// NormalizeHandle normalizes handle format (removes at:// prefix if present)
+func NormalizeHandle(handle string) string {
+	handle = strings.TrimPrefix(handle, "at://")
+	handle = strings.TrimPrefix(handle, "@")
+	return handle
+}