probo/pkg/accessreview/drivers/docusign.go

// Copyright (c) 2026 Probo Inc <hello@getprobo.com>.
//
// Permission to use, copy, modify, and/or distribute this software for any
// purpose with or without fee is hereby granted, provided that the above
// copyright notice and this permission notice appear in all copies.
//
// THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
// REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
// AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
// INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
// LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
// OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
// PERFORMANCE OF THIS SOFTWARE.

package drivers

import (
	"context"
	"encoding/json"
	"fmt"
	"net/http"
	"net/url"
	"strconv"
	"strings"
	"time"

	"go.probo.inc/probo/pkg/coredata"
)

// DocuSignDriver fetches account users from DocuSign via OAuth2-authenticated
// REST API requests. It auto-discovers the account ID and base URI from the
// OAuth2 userinfo endpoint, then paginates through the eSignature Users API.
type DocuSignDriver struct {
	httpClient *http.Client
}

var _ Driver = (*DocuSignDriver)(nil)

type docusignUserInfoResponse struct {
	Accounts []struct {
		AccountID string `json:"account_id"`
		IsDefault bool   `json:"is_default"`
		BaseURI   string `json:"base_uri"`
	} `json:"accounts"`
}

type docusignUsersResponse struct {
	Users []struct {
		UserID                string `json:"userId"`
		UserName              string `json:"userName"`
		Email                 string `json:"email"`
		UserStatus            string `json:"userStatus"`
		IsAdmin               string `json:"isAdmin"`
		CreatedDateTime       string `json:"createdDateTime"`
		LastLogin             string `json:"lastLogin"`
		PermissionProfileName string `json:"permissionProfileName"`
		JobTitle              string `json:"jobTitle"`
	} `json:"users"`
	ResultSetSize string `json:"resultSetSize"`
	TotalSetSize  string `json:"totalSetSize"`
	StartPosition string `json:"startPosition"`
	EndPosition   string `json:"endPosition"`
}

const (
	docusignUserInfoEndpoint = "https://account.docusign.com/oauth/userinfo"
	docusignUsersPageSize    = 100
)

func NewDocuSignDriver(httpClient *http.Client) *DocuSignDriver {
	return &DocuSignDriver{
		httpClient: httpClient,
	}
}

func (d *DocuSignDriver) ListAccounts(ctx context.Context) ([]AccountRecord, error) {
	accountID, baseURI, err := d.discoverAccount(ctx)
	if err != nil {
		return nil, fmt.Errorf("cannot discover docusign account: %w", err)
	}

	var records []AccountRecord

	startPosition := 0

	for range maxPaginationPages {
		resp, err := d.queryUsers(ctx, baseURI, accountID, startPosition)
		if err != nil {
			return nil, err
		}

		for _, u := range resp.Users {
			record := AccountRecord{
				Email:       u.Email,
				FullName:    u.UserName,
				Role:        u.PermissionProfileName,
				JobTitle:    u.JobTitle,
				Active:      new(strings.EqualFold(u.UserStatus, "active")),
				IsAdmin:     strings.EqualFold(u.IsAdmin, "True"),
				ExternalID:  u.UserID,
				MFAStatus:   coredata.MFAStatusUnknown,
				AuthMethod:  coredata.AccessEntryAuthMethodUnknown,
				AccountType: coredata.AccessEntryAccountTypeUser,
			}

			if u.LastLogin != "" {
				if t, err := time.Parse(time.RFC3339, u.LastLogin); err == nil {
					record.LastLogin = &t
				}
			}

			if u.CreatedDateTime != "" {
				if t, err := time.Parse(time.RFC3339, u.CreatedDateTime); err == nil {
					record.CreatedAt = &t
				}
			}

			if record.Email != "" {
				records = append(records, record)
			}
		}

		totalSetSize, err := strconv.Atoi(resp.TotalSetSize)
		if err != nil {
			return nil, fmt.Errorf("cannot parse docusign total set size %q: %w", resp.TotalSetSize, err)
		}

		endPosition, err := strconv.Atoi(resp.EndPosition)
		if err != nil {
			return nil, fmt.Errorf("cannot parse docusign end position %q: %w", resp.EndPosition, err)
		}

		if totalSetSize == 0 || endPosition >= totalSetSize-1 {
			return records, nil
		}

		startPosition = endPosition + 1
	}

	return nil, fmt.Errorf("cannot list all docusign accounts: %w", ErrPaginationLimitReached)
}

func (d *DocuSignDriver) discoverAccount(ctx context.Context) (accountID string, baseURI string, err error) {
	req, err := http.NewRequestWithContext(ctx, http.MethodGet, docusignUserInfoEndpoint, nil)
	if err != nil {
		return "", "", fmt.Errorf("cannot create docusign userinfo request: %w", err)
	}

	req.Header.Set("Accept", "application/json")

	httpResp, err := d.httpClient.Do(req)
	if err != nil {
		return "", "", fmt.Errorf("cannot execute docusign userinfo request: %w", err)
	}

	defer func() {
		_ = httpResp.Body.Close()
	}()

	if httpResp.StatusCode < 200 || httpResp.StatusCode >= 300 {
		return "", "", fmt.Errorf("cannot fetch docusign userinfo: unexpected status %d", httpResp.StatusCode)
	}

	var resp docusignUserInfoResponse
	if err := json.NewDecoder(httpResp.Body).Decode(&resp); err != nil {
		return "", "", fmt.Errorf("cannot decode docusign userinfo response: %w", err)
	}

	for _, account := range resp.Accounts {
		if account.IsDefault {
			return account.AccountID, account.BaseURI, nil
		}
	}

	if len(resp.Accounts) > 0 {
		return resp.Accounts[0].AccountID, resp.Accounts[0].BaseURI, nil
	}

	return "", "", fmt.Errorf("no docusign accounts found in userinfo response")
}

func (d *DocuSignDriver) queryUsers(ctx context.Context, baseURI string, accountID string, startPosition int) (*docusignUsersResponse, error) {
	u, err := url.JoinPath(baseURI, "restapi", "v2.1", "accounts", url.PathEscape(accountID), "users")
	if err != nil {
		return nil, fmt.Errorf("cannot build docusign users URL: %w", err)
	}

	parsed, err := url.Parse(u)
	if err != nil {
		return nil, fmt.Errorf("cannot parse docusign users URL: %w", err)
	}

	q := parsed.Query()
	q.Set("additional_info", "true")
	q.Set("count", strconv.Itoa(docusignUsersPageSize))
	q.Set("start_position", strconv.Itoa(startPosition))
	parsed.RawQuery = q.Encode()

	req, err := http.NewRequestWithContext(ctx, http.MethodGet, parsed.String(), nil)
	if err != nil {
		return nil, fmt.Errorf("cannot create docusign users request: %w", err)
	}

	req.Header.Set("Accept", "application/json")

	httpResp, err := d.httpClient.Do(req)
	if err != nil {
		return nil, fmt.Errorf("cannot execute docusign users request: %w", err)
	}

	defer func() {
		_ = httpResp.Body.Close()
	}()

	if httpResp.StatusCode < 200 || httpResp.StatusCode >= 300 {
		return nil, fmt.Errorf("cannot fetch docusign users: unexpected status %d", httpResp.StatusCode)
	}

	var resp docusignUsersResponse
	if err := json.NewDecoder(httpResp.Body).Decode(&resp); err != nil {
		return nil, fmt.Errorf("cannot decode docusign users response: %w", err)
	}

	return &resp, nil
}