Skip to content

High-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.

7.2 KB
Raw Blame
package audit

import (
	"encoding/base64"
	"strings"

	"github.com/pinchtab/pinchtab/internal/bridge"
	"github.com/pinchtab/pinchtab/internal/bridge/observe"
)

// PageOptions selects which collectors run when enriching a page.
type PageOptions struct {
	Screenshot bool `json:"screenshot"`
	Network    bool `json:"network"`
	// Console captures both page-message channels: console calls and
	// uncaught JavaScript exceptions.
	Console  bool `json:"console"`
	A11y     bool `json:"a11y"`
	Timing   bool `json:"timing"`
	Elements bool `json:"elements"`
	Security bool `json:"security"`
}

// DefaultPageOptions enables every collector.
func DefaultPageOptions() PageOptions {
	return PageOptions{Screenshot: true, Network: true, Console: true, A11y: true, Timing: true, Elements: true, Security: true}
}

// Collectors are the browser-backed data sources EnrichPage composes. Hooks
// for disabled options may be nil.
type Collectors struct {
	Title      func() (string, error)
	Screenshot func() ([]byte, error)
	Console    func() ([]bridge.LogEntry, error)
	JSErrors   func() ([]bridge.ErrorEntry, error)
	Network    func() ([]observe.NetworkEntry, error)
	Snapshot   func() ([]observe.A11yNode, error)
	PageFacts  func() (PageFacts, error)
	Timing     func() (*observe.TimingMetrics, error)
	Forms      func() ([]FormFact, error)
}

// PageAudit is the audit result for one page. Collector failures are data,
// not errors: they land in Error while the remaining fields stay populated.
type PageAudit struct {
	// URL is the audited page URL as requested.
	URL string `json:"url"`
	// Title is the page title after navigation.
	Title string `json:"title,omitempty"`
	// Error describes navigation or collector failures, empty on success.
	Error string `json:"error,omitempty"`
	// Screenshot is the base64-encoded PNG when screenshot capture is on.
	Screenshot string `json:"screenshot,omitempty"`
	// A11yFindings are the accessibility rule violations behind AccessibilityScore.
	A11yFindings []A11yFinding `json:"a11yFindings,omitempty"`
	// SecurityFindings are the page's rule-based security-surface findings.
	SecurityFindings []SecurityFinding `json:"securityFindings,omitempty"`
	BrowserPageData
}

// NewPageAuditError returns the structured entry for a page that could not
// be navigated at all.
func NewPageAuditError(url string, err error) PageAudit {
	return PageAudit{URL: url, Error: err.Error()}
}

// EnrichPage assembles a PageAudit from an already-navigated page via the
// given collectors, honoring opts. Individual collector failures never abort
// the audit; they are recorded in the Error field.
func EnrichPage(url string, opts PageOptions, c Collectors) PageAudit {
	pa := PageAudit{URL: url}
	var errs []string
	fail := func(stage string, err error) { errs = append(errs, stage+": "+err.Error()) }

	if c.Title != nil {
		if title, err := c.Title(); err == nil {
			pa.Title = title
		}
	}

	if opts.Console && c.Console != nil {
		if logs, err := c.Console(); err != nil {
			fail("console", err)
		} else {
			pa.ConsoleLogs = MapConsoleLogs(logs)
		}
	}

	if opts.Console && c.JSErrors != nil {
		if errors, err := c.JSErrors(); err != nil {
			fail("jsErrors", err)
		} else {
			pa.JSErrors = MapJSErrors(errors)
		}
	}

	if opts.Network && c.Network != nil {
		if entries, err := c.Network(); err != nil {
			fail("network", err)
		} else {
			pa.NetworkRequests = MapNetworkRequests(entries)
			pa.BrokenAssets = MapBrokenAssets(observe.BrokenAssets(entries))
		}
	}

	var nodes []observe.A11yNode
	if (opts.Elements || opts.A11y) && c.Snapshot != nil {
		var err error
		if nodes, err = c.Snapshot(); err != nil {
			fail("snapshot", err)
			nodes = nil
		}
	}
	if opts.Elements {
		pa.InteractiveElements = MapInteractiveElements(nodes)
	}
	if opts.A11y && c.PageFacts != nil {
		if facts, err := c.PageFacts(); err != nil {
			fail("a11y", err)
		} else {
			report := EvaluateA11y(nodes, facts)
			pa.AccessibilityScore = report.Score
			pa.A11yFindings = report.Findings
		}
	}

	if opts.Timing && c.Timing != nil {
		if timing, err := c.Timing(); err != nil {
			fail("timing", err)
		} else if timing != nil {
			pa.TimingMetrics = MapTimingMetrics(*timing)
		}
	}

	if opts.Screenshot && c.Screenshot != nil {
		if png, err := c.Screenshot(); err != nil {
			fail("screenshot", err)
		} else {
			pa.Screenshot = base64.StdEncoding.EncodeToString(png)
		}
	}

	if opts.Security {
		var forms []FormFact
		if c.Forms != nil {
			var err error
			if forms, err = c.Forms(); err != nil {
				fail("security", err)
				forms = nil
			}
		}
		pa.SecurityFindings = EvaluateSecurity(url, pa.Title, pa.NetworkRequests, forms)
	}

	pa.Error = strings.Join(errs, "; ")
	return pa
}

// MapConsoleLogs converts bridge console entries to the audit schema.
func MapConsoleLogs(logs []bridge.LogEntry) []ConsoleLogEntry {
	out := make([]ConsoleLogEntry, 0, len(logs))
	for _, l := range logs {
		out = append(out, ConsoleLogEntry{
			Timestamp: l.Timestamp,
			Level:     l.Level,
			Message:   l.Message,
			Source:    l.Source,
		})
	}
	return out
}

// MapJSErrors converts bridge uncaught-exception entries to the audit schema.
func MapJSErrors(errors []bridge.ErrorEntry) []JSError {
	out := make([]JSError, 0, len(errors))
	for _, e := range errors {
		out = append(out, JSError{
			Timestamp: e.Timestamp,
			Message:   e.Message,
			Type:      e.Type,
			URL:       e.URL,
			Line:      e.Line,
			Column:    e.Column,
			Stack:     e.Stack,
		})
	}
	return out
}

// MapNetworkRequests converts observed network entries to the audit schema.
func MapNetworkRequests(entries []observe.NetworkEntry) []NetworkRequest {
	out := make([]NetworkRequest, 0, len(entries))
	for _, e := range entries {
		out = append(out, NetworkRequest{
			URL:          e.URL,
			Method:       e.Method,
			Status:       e.Status,
			StatusText:   e.StatusText,
			ResourceType: e.ResourceType,
			MimeType:     e.MimeType,
			StartTime:    e.StartTime,
			Duration:     e.Duration,
			Size:         e.Size,
			Failed:       e.Failed || e.Status >= 400,
			Error:        e.Error,
		})
	}
	return out
}

// MapBrokenAssets converts observe broken-asset entries to the audit schema.
func MapBrokenAssets(assets []observe.BrokenAsset) []BrokenAsset {
	out := make([]BrokenAsset, 0, len(assets))
	for _, a := range assets {
		out = append(out, BrokenAsset{
			URL:          a.URL,
			ResourceType: a.ResourceType,
			Status:       a.StatusCode,
			Error:        a.Error,
		})
	}
	return out
}

// MapInteractiveElements extracts the visible interactive elements from a
// full accessibility snapshot.
func MapInteractiveElements(nodes []observe.A11yNode) []InteractiveElement {
	out := make([]InteractiveElement, 0)
	for _, n := range nodes {
		if n.Hidden || !observe.InteractiveRoles[n.Role] {
			continue
		}
		out = append(out, InteractiveElement{
			Ref:      n.Ref,
			Role:     n.Role,
			Name:     n.Name,
			Tag:      n.Tag,
			Label:    n.Label,
			Disabled: n.Disabled,
		})
	}
	return out
}

// MapTimingMetrics converts observe timing metrics to the audit schema.
func MapTimingMetrics(t observe.TimingMetrics) BrowserTimingMetrics {
	return BrowserTimingMetrics{
		TimeToFirstByte:        t.TTFBMs,
		DOMContentLoaded:       t.DOMContentLoadedMs,
		Load:                   t.LoadMs,
		FirstContentfulPaint:   t.FCPMs,
		LargestContentfulPaint: t.LCPMs,
		CumulativeLayoutShift:  t.CLS,
	}
}