PDF Tamper Detection API for Go: Integration Guide

curl -X POST https://api.htpbe.tech/v1/analyze \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://api.htpbe.tech/v1/test/clean.pdf"}'

curl https://api.htpbe.tech/v1/result/YOUR_CHECK_ID \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "id": "00000000-0000-4000-8000-000000000001",
  "status": "intact",
  "origin": { "type": "institutional", "software": null },
  "creator": "Adobe Acrobat Pro DC",
  "producer": "Adobe PDF Library 15.0",
  "modification_confidence": "none",
  "has_incremental_updates": false,
  "update_chain_length": 1,
  "signature_removed": false,
  "modifications_after_signature": false,
  "modification_markers": []
}

package htpbe

// Result mirrors the flat GET /result/{id} response.
// Nullable fields use pointers so "absent" is distinguishable from zero.
type Result struct {
	ID       string `json:"id"`
	Filename string `json:"filename"`
	FileSize int64  `json:"file_size"`
	PageCount int   `json:"page_count"`

	AlgorithmVersion        string `json:"algorithm_version"`
	CurrentAlgorithmVersion string `json:"current_algorithm_version"`
	OutdatedWarning         string `json:"outdated_warning"`

	// Primary verdict: "intact" | "modified" | "inconclusive"
	Status string `json:"status"`
	// StatusReason is present only when Status == "inconclusive":
	// "consumer_software_origin" | "online_editor_origin" |
	// "scanned_document" | "html_renderer_origin"
	StatusReason string `json:"status_reason"`

	Origin struct {
		// "consumer_software" | "institutional" | "unknown" |
		// "online_editor" | "scanned"
		Type     string  `json:"type"`
		Software *string `json:"software"`
	} `json:"origin"`

	// "certain" | "high" | "none" | null
	ModificationConfidence *string `json:"modification_confidence"`

	Creator          *string `json:"creator"`
	Producer         *string `json:"producer"`
	CreationDate     *int64  `json:"creation_date"`     // Unix seconds
	ModificationDate *int64  `json:"modification_date"` // Unix seconds
	PDFVersion       *string `json:"pdf_version"`

	DateSequenceValid         bool `json:"date_sequence_valid"`
	MetadataCompletenessScore int  `json:"metadata_completeness_score"`

	XrefCount            int  `json:"xref_count"`
	HasIncrementalUpdates bool `json:"has_incremental_updates"`
	UpdateChainLength    int  `json:"update_chain_length"`

	HasDigitalSignature        bool `json:"has_digital_signature"`
	SignatureCount             int  `json:"signature_count"`
	SignatureRemoved           bool `json:"signature_removed"`
	ModificationsAfterSignature bool `json:"modifications_after_signature"`

	ObjectCount      int  `json:"object_count"`
	HasJavascript    bool `json:"has_javascript"`
	HasEmbeddedFiles bool `json:"has_embedded_files"`

	// Stable HTPBE_* marker ids, e.g. ["HTPBE_SIGNATURE_REMOVED"].
	// Empty when Status is "intact" or "inconclusive".
	ModificationMarkers []string `json:"modification_markers"`
}

const (
	StatusIntact       = "intact"
	StatusModified     = "modified"
	StatusInconclusive = "inconclusive"
)

package htpbe

import "fmt"

// APIError is returned for any non-2xx response from the API.
type APIError struct {
	StatusCode      int
	Code            string // machine-readable code from the JSON body, when present
	Message         string
	RetryAfterSecs  int // parsed from Retry-After on 429; 0 when absent
}

func (e *APIError) Error() string {
	return fmt.Sprintf("htpbe: %d %s: %s", e.StatusCode, e.Code, e.Message)
}

// Retryable reports whether retrying the same request could succeed.
// Only 5xx and 429 are transient; 4xx (other than 429) are permanent.
func (e *APIError) Retryable() bool {
	return e.StatusCode >= 500 || e.StatusCode == 429
}

package htpbe

import (
	"bytes"
	"context"
	"encoding/json"
	"errors"
	"fmt"
	"io"
	"net/http"
	"strconv"
	"strings"
	"time"
)

const defaultBaseURL = "https://api.htpbe.tech/v1"

// Client is a reusable, concurrency-safe HTPBE API client.
type Client struct {
	apiKey     string
	baseURL    string
	httpClient *http.Client
	maxRetries int
}

// Option configures a Client.
type Option func(*Client)

// WithHTTPClient overrides the default *http.Client. A nil value is ignored
// so the option can never produce a nil-deref at request time.
func WithHTTPClient(hc *http.Client) Option {
	return func(c *Client) {
		if hc != nil {
			c.httpClient = hc
		}
	}
}
func WithBaseURL(u string) Option { return func(c *Client) { c.baseURL = u } }
func WithMaxRetries(n int) Option { return func(c *Client) { c.maxRetries = n } }

// New constructs a Client. The apiKey is required.
func New(apiKey string, opts ...Option) (*Client, error) {
	if apiKey == "" {
		return nil, errors.New("htpbe: API key is required")
	}
	c := &Client{
		apiKey:     apiKey,
		baseURL:    defaultBaseURL,
		httpClient: &http.Client{Timeout: 35 * time.Second},
		maxRetries: 3,
	}
	for _, opt := range opts {
		opt(c)
	}
	// Tolerate a trailing slash so callers can pass either form of the base URL.
	c.baseURL = strings.TrimRight(c.baseURL, "/")
	return c, nil
}

type analyzeRequest struct {
	URL              string `json:"url"`
	OriginalFilename string `json:"original_filename,omitempty"`
}

type analyzeResponse struct {
	ID string `json:"id"`
}

type errorBody struct {
	Error string `json:"error"`
	Code  string `json:"code"`
}

// Verify submits a PDF URL and returns the full verdict. The two steps are
// retried independently: POST /analyze (the billable step) is retried until
// it yields an id, then GET /result/{id} (a free read) is retried on its own.
// A failed GET never replays the POST, so a transient read failure cannot
// create a duplicate analysis job. The context governs cancellation and the
// overall deadline.
//
// originalFilename is optional; pass it so the result's `filename` field
// shows a human-readable name instead of an opaque storage key.
func (c *Client) Verify(ctx context.Context, pdfURL, originalFilename string) (*Result, error) {
	if pdfURL == "" {
		return nil, errors.New("htpbe: pdfURL is required")
	}

	// Step 1: submit for analysis (billable — retried in isolation).
	id, err := c.withRetry(ctx, func() (string, error) {
		return c.submitAnalysis(ctx, pdfURL, originalFilename)
	})
	if err != nil {
		return nil, err
	}

	// Step 2: read the result (free — retried in isolation, never replays POST).
	var result *Result
	_, err = c.withRetry(ctx, func() (string, error) {
		r, e := c.getResult(ctx, id)
		if e != nil {
			return "", e
		}
		result = r
		return id, nil
	})
	if err != nil {
		return nil, err
	}
	return result, nil
}

// withRetry runs op until it succeeds, backing off only on Retryable() API
// errors (5xx, 429). It honours a parsed Retry-After and the context deadline.
func (c *Client) withRetry(ctx context.Context, op func() (string, error)) (string, error) {
	var lastErr error
	for attempt := 0; attempt <= c.maxRetries; attempt++ {
		if attempt > 0 {
			// Honour a server-supplied Retry-After on 429; otherwise
			// exponential backoff: 1s, 2s, 4s.
			delay := time.Duration(1<<(attempt-1)) * time.Second
			var apiErr *APIError
			if errors.As(lastErr, &apiErr) && apiErr.RetryAfterSecs > 0 {
				delay = time.Duration(apiErr.RetryAfterSecs) * time.Second
			}
			select {
			case <-ctx.Done():
				return "", ctx.Err()
			case <-time.After(delay):
			}
		}

		v, err := op()
		if err == nil {
			return v, nil
		}
		lastErr = err
		if apiErr := asAPIError(err); apiErr != nil && !apiErr.Retryable() {
			return "", err // permanent — do not retry
		}
	}
	return "", fmt.Errorf("htpbe: exhausted retries: %w", lastErr)
}

func (c *Client) submitAnalysis(ctx context.Context, pdfURL, originalFilename string) (string, error) {
	body, err := json.Marshal(analyzeRequest{URL: pdfURL, OriginalFilename: originalFilename})
	if err != nil {
		return "", fmt.Errorf("htpbe: marshal request: %w", err)
	}

	req, err := http.NewRequestWithContext(ctx, http.MethodPost,
		c.baseURL+"/analyze", bytes.NewReader(body))
	if err != nil {
		return "", err
	}
	req.Header.Set("Authorization", "Bearer "+c.apiKey)
	req.Header.Set("Content-Type", "application/json")

	resp, err := c.httpClient.Do(req)
	if err != nil {
		return "", fmt.Errorf("htpbe: analyze request: %w", err)
	}
	defer resp.Body.Close()

	if resp.StatusCode/100 != 2 {
		return "", parseError(resp)
	}

	var ar analyzeResponse
	if err := json.NewDecoder(resp.Body).Decode(&ar); err != nil {
		return "", fmt.Errorf("htpbe: decode analyze response: %w", err)
	}
	if ar.ID == "" {
		return "", errors.New("htpbe: analyze response missing id")
	}
	return ar.ID, nil
}

func (c *Client) getResult(ctx context.Context, id string) (*Result, error) {
	req, err := http.NewRequestWithContext(ctx, http.MethodGet,
		c.baseURL+"/result/"+id, nil)
	if err != nil {
		return nil, err
	}
	req.Header.Set("Authorization", "Bearer "+c.apiKey)

	resp, err := c.httpClient.Do(req)
	if err != nil {
		return nil, fmt.Errorf("htpbe: result request: %w", err)
	}
	defer resp.Body.Close()

	if resp.StatusCode/100 != 2 {
		return nil, parseError(resp)
	}

	var result Result
	if err := json.NewDecoder(resp.Body).Decode(&result); err != nil {
		return nil, fmt.Errorf("htpbe: decode result: %w", err)
	}
	return &result, nil
}

// parseError builds a typed APIError from a non-2xx response.
func parseError(resp *http.Response) error {
	raw, _ := io.ReadAll(io.LimitReader(resp.Body, 1<<16))

	var eb errorBody
	_ = json.Unmarshal(raw, &eb) // best effort — body may not be JSON

	apiErr := &APIError{
		StatusCode: resp.StatusCode,
		Code:       eb.Code,
		Message:    eb.Error,
	}
	if apiErr.Message == "" {
		apiErr.Message = http.StatusText(resp.StatusCode)
	}

	switch resp.StatusCode {
	case http.StatusUnauthorized: // 401
		apiErr.Message = "invalid API key — check the HTPBE_API_KEY environment variable"
	case http.StatusPaymentRequired: // 402
		apiErr.Message = "no credits available for this key — top up or subscribe"
	case http.StatusRequestEntityTooLarge: // 413
		apiErr.Message = "PDF exceeds the 10 MB size limit"
	case http.StatusUnprocessableEntity: // 422
		apiErr.Message = "the URL did not return a valid PDF file"
	case http.StatusTooManyRequests: // 429
		apiErr.RetryAfterSecs = parseRetryAfter(resp.Header.Get("Retry-After"))
	}
	return apiErr
}

// parseRetryAfter handles the delay-seconds form ("30") and the HTTP-date
// form, clamping the result to a sane [1, 600] range. Returns 0 when absent
// or unparseable so callers fall back to their own backoff.
func parseRetryAfter(h string) int {
	if h == "" {
		return 0
	}
	if secs, err := strconv.Atoi(h); err == nil {
		return clamp(secs, 1, 600)
	}
	if t, err := http.ParseTime(h); err == nil {
		return clamp(int(time.Until(t).Seconds()), 1, 600)
	}
	return 0
}

func clamp(v, lo, hi int) int {
	if v < lo {
		return lo
	}
	if v > hi {
		return hi
	}
	return v
}

func asAPIError(err error) *APIError {
	var apiErr *APIError
	if errors.As(err, &apiErr) {
		return apiErr
	}
	return nil
}

package htpbe

// Decision is the routing outcome for a verified document.
type Decision string

const (
	Accept Decision = "accept"
	Reject Decision = "reject"
	Review Decision = "review"
)

// GateInstitutional maps a verdict to a decision for documents that
// claim institutional origin (bank statements, payslips, diplomas).
// For these, "inconclusive" is treated as strictly as "modified":
// a document that should have come from a bank's system but looks
// like it was built in Word does not get the benefit of the doubt.
func GateInstitutional(r *Result) Decision {
	switch r.Status {
	case StatusModified:
		return Reject
	case StatusInconclusive:
		// A bank statement that comes back inconclusive should not be
		// auto-accepted: it typically came from consumer software rather
		// than a bank's own system, which is a signal to route for review
		// — not proof of tampering. Route to a human.
		return Review
	default: // StatusIntact
		return Accept
	}
}

package main

import (
	"context"
	"encoding/json"
	"errors"
	"log/slog"
	"net/http"
	"os"
	"time"

	"yourapp/htpbe"
)

type verifyRequest struct {
	DocumentURL      string `json:"document_url"`
	OriginalFilename string `json:"original_filename"`
}

func main() {
	client, err := htpbe.New(os.Getenv("HTPBE_API_KEY"))
	if err != nil {
		slog.Error("htpbe init failed", "err", err)
		os.Exit(1)
	}

	http.HandleFunc("POST /api/documents", func(w http.ResponseWriter, req *http.Request) {
		var body verifyRequest
		if err := json.NewDecoder(req.Body).Decode(&body); err != nil || body.DocumentURL == "" {
			http.Error(w, `{"error":"document_url is required"}`, http.StatusBadRequest)
			return
		}

		// Bound the whole two-step round trip to 40 seconds.
		ctx, cancel := context.WithTimeout(req.Context(), 40*time.Second)
		defer cancel()

		result, err := client.Verify(ctx, body.DocumentURL, body.OriginalFilename)
		if err != nil {
			var apiErr *htpbe.APIError
			if errors.As(err, &apiErr) {
				switch apiErr.StatusCode {
				case http.StatusUnauthorized, http.StatusPaymentRequired:
					// Configuration / billing error — never expose details to the caller.
					slog.Error("htpbe misconfigured", "code", apiErr.Code)
					http.Error(w, `{"error":"verification temporarily unavailable"}`, http.StatusServiceUnavailable)
					return
				case http.StatusUnprocessableEntity:
					http.Error(w, `{"error":"the URL did not return a valid PDF"}`, http.StatusUnprocessableEntity)
					return
				case http.StatusRequestEntityTooLarge:
					http.Error(w, `{"error":"PDF must be under 10 MB"}`, http.StatusRequestEntityTooLarge)
					return
				}
			}
			slog.Error("htpbe verify failed", "err", err)
			http.Error(w, `{"error":"verification failed"}`, http.StatusBadGateway)
			return
		}

		switch htpbe.GateInstitutional(result) {
		case htpbe.Reject:
			writeJSON(w, http.StatusUnprocessableEntity, map[string]any{
				"decision":             "reject",
				"reason":               "document modified after creation",
				"modification_markers": result.ModificationMarkers,
			})
		case htpbe.Review:
			writeJSON(w, http.StatusAccepted, map[string]any{
				"decision":      "review",
				"status_reason": result.StatusReason,
			})
		default: // Accept
			writeJSON(w, http.StatusOK, map[string]any{
				"decision": "accept",
				"check_id": result.ID,
			})
		}
	})

	slog.Info("listening on :8080")
	_ = http.ListenAndServe(":8080", nil)
}

func writeJSON(w http.ResponseWriter, status int, v any) {
	w.Header().Set("Content-Type", "application/json")
	w.WriteHeader(status)
	_ = json.NewEncoder(w).Encode(v)
}

// Store the upload privately, mint a 5-minute presigned GET URL, verify.
key := "incoming/" + uuid.NewString() + ".pdf"
if _, err := s3Client.PutObject(ctx, &s3.PutObjectInput{
	Bucket: &bucket, Key: &key,
	Body: bytes.NewReader(data), ContentType: aws.String("application/pdf"),
}); err != nil {
	return nil, err
}
presigned, err := presigner.PresignGetObject(ctx, &s3.GetObjectInput{
	Bucket: &bucket, Key: &key,
}, s3.WithPresignExpires(5*time.Minute))
if err != nil {
	return nil, err
}
return client.Verify(ctx, presigned.URL, originalFilename)

func verifyBatch(ctx context.Context, client *htpbe.Client, urls []string) map[string]*htpbe.Result {
	const workers = 8 // stay within your plan's concurrency comfort zone
	sem := make(chan struct{}, workers)
	results := make(map[string]*htpbe.Result)
	var mu sync.Mutex
	var wg sync.WaitGroup

	for _, u := range urls {
		wg.Add(1)
		sem <- struct{}{}
		go func(pdfURL string) {
			defer wg.Done()
			defer func() { <-sem }()
			r, err := client.Verify(ctx, pdfURL, "")
			if err != nil {
				slog.Warn("verify failed", "url", pdfURL, "err", err)
				return
			}
			mu.Lock()
			results[pdfURL] = r
			mu.Unlock()
		}(u)
	}
	wg.Wait()
	return results
}