[CXH-2209] fix: gate clm_role on CLM availability, narrow opt-in error tolerance, log skipped folder-security entries

.github/workflows/ci.yaml

@@ -5,17 +5,32 @@ on:
   push:
     branches:
       - main
-# Workflow-level (not per-job): all three jobs below hit the same shared DocuSign demo
-# account, and running two runs' Grant/Revoke cycles concurrently races on that account's
-# real state (one run's mid-cycle Grant/Revoke can make another run's "should be zero
-# grants after Revoke" assertion fail). A per-job concurrency block only protects a
-# *running* job from cancellation — GitHub Actions still cancels a *pending* job in the
-# same group when a newer one queues. Declaring it once here makes the whole
-# needs-chained run (all three jobs) queue/cancel as one unit against the shared group.
+# Workflow-level, not per-job: all three jobs share the DocuSign demo account, and a
+# per-job block only protects a *running* job — GitHub Actions still cancels a *pending*
+# job in the same group when a newer run queues. Declaring it once here queues/cancels
+# all three jobs as one unit.
 concurrency:
   group: docusign-demo-account
   cancel-in-progress: false
 env:
+  # This CI account has no CLM subscription, and (unlike a C1-hosted sync) nothing here
+  # filters resource types by OptInRequired — every registered resource type is attempted
+  # by default. CLM builders now fail the whole sync rather than skip gracefully when CLM
+  # isn't available (see pkg/connector/clm_roles.go), so the 5 clm_* types must be
+  # excluded here explicitly to test the ones the three test-* jobs below care about.
+  # This is an allowlist, not a CLM-only exclusion: if you register a new non-CLM
+  # resource type in pkg/connector/connector.go, add it here too — otherwise it silently
+  # gets zero CI sync-test coverage. Declared once at the workflow level (all three jobs
+  # inherit it) so there's no per-job copy to keep in sync.
+  #
+  # signing_group specifically only works here because every job below also sets
+  # BATON_INCLUDE_SIGNING_GROUPS: "true" — the connector only advertises signing_group
+  # via ListResourceTypes() when that flag is set (pkg/connector/connector.go), and the
+  # SDK hard-errors on any filter entry the connector doesn't advertise
+  # ("invalid resource type 'signing_group' in filter"). If a future job drops that
+  # per-job env var, it fails with that confusing filter error instead of just skipping
+  # signing groups.
+  BATON_SYNC_RESOURCE_TYPES: user,group,permission_profile,signing_group
   # Forces the legacy v1/SQLite c1z format instead of baton-sdk v0.25.0's new default
   # (Pebble/v3). The `baton` CLI these jobs download (ConductorOne/github-workflows'
   # get-baton action, currently v0.4.5) is built against baton-sdk v0.8.24 — long before

README.md

@@ -101,9 +101,9 @@ Copy the `code` parameter value and paste it when prompted. Save the refresh tok
 
 DocuSign CLM (Contract Lifecycle Management) is a separate DocuSign product from
 eSignature, with its own API and a separate production subscription. CLM members, roles,
-groups, folders, folder security, and permission sets sync alongside the standard
-eSignature resources, with no config flag to enable — accounts that don't have CLM simply
-sync no CLM resources.
+groups, folders, folder security, and permission sets are opt-in: they don't sync by
+default, and a customer must explicitly enable each CLM resource type in C1's sync
+configuration.
 
 Requirements:
 
@@ -115,11 +115,32 @@ Requirements:
   also be granted the CLM API scopes on ConductorOne's platform side before any CLM data
   will sync. Contact ConductorOne if no CLM data appears in this mode.
 
-The 5 CLM resource types are always registered and visible to C1 — this avoids a C1 sync
-engine treating CLM resources as deleted if they stop appearing (see
-[CHANGE_TYPES.md](CHANGE_TYPES.md) if you're touching this). Without the CLM OAuth scopes
-(or without a CLM subscription on the account), each CLM resource type's sync is skipped
-gracefully rather than erroring the whole sync.
+The 5 CLM resource types are always registered and visible to C1, but each carries
+`OptInRequired` — C1 excludes them from a customer's sync by default, and they only run
+once a customer explicitly opts in (see [CHANGE_TYPES.md](CHANGE_TYPES.md) if you're
+touching this). C1's opt-in toggle does not validate the underlying DocuSign account
+first, so a customer can enable CLM sync without actually having the subscription or
+scopes above. If that happens, the sync fails loudly rather than silently succeeding
+with zero CLM resources — an account that opted in but can't reach CLM is treated as a
+misconfiguration to fix (disable the resource type, or activate the CLM feature), not an
+expected state to tolerate.
+
+`OptInRequired` is enforced by ConductorOne's platform, not by the connector or baton-sdk
+itself — a self-hosted connector running in service mode still has its per-resource-type
+`List()` calls filtered by the platform's opt-in selection (applied inside baton-sdk's
+syncer, not surfaced to the connector's own code), but running `baton-docusign` directly
+as a one-shot CLI sync (the quickstarts below, with no service/task involved at all)
+attempts all 5 CLM resource types by default, with no opt-in gate at all. If that account
+doesn't have a CLM subscription, the sync now fails instead of skipping CLM gracefully.
+Pass `--sync-resource-types` (or `BATON_SYNC_RESOURCE_TYPES`, comma-separated) with the
+resource type IDs you actually want (e.g. `user,group,permission_profile`) to exclude
+`clm_member,clm_role,clm_group,clm_permission_set,clm_folder` on an eSignature-only
+account run this way.
+
+One check does NOT see that platform filter in either deployment mode: `Connector.Validate()`'s
+upfront CLM-readiness check runs once, before any resource type's `List()` and before the
+platform filter is applied to anything — a known, reviewed, and deliberately accepted gap,
+not an oversight.
 
 CLM permission sets sync for visibility only — DocuSign's CLM API has no endpoint to
 assign or unassign a permission set, so they cannot be granted or revoked through this

docs/connector.mdx

@@ -26,9 +26,9 @@ The Docusign connector supports [automatic account provisioning and deprovisioni
 
 Every Docusign account must be assigned at least one permission profile. If all other permission profiles are revoked, the account will be automatically assigned the **DocuSign Viewer** profile, which cannot be revoked.
 
-*By default, signing groups are not synced. Enable the **Include Signing Groups** setting to sync signing groups, if your account has the feature enabled.
+*By default, signing groups are not synced. Enable the **Include Signing Groups** setting to sync signing groups. Once enabled, your account must actually have the signing groups feature — ConductorOne doesn't validate this before letting you turn the setting on, so enabling it without the feature will fail the sync rather than silently sync no signing groups.
 
-**DocuSign CLM (Contract Lifecycle Management) is a separate, separately-licensed DocuSign product. CLM resources sync automatically if the account has a DocuSign CLM production subscription and the credential has been granted the OAuth scopes CLM needs; accounts without CLM simply sync no CLM resources. CLM permission sets sync for visibility only; DocuSign's CLM API has no endpoint to assign or unassign one.
+**DocuSign CLM (Contract Lifecycle Management) is a separate, separately-licensed DocuSign product. CLM resources are opt-in — enable each CLM resource type in your sync configuration to turn them on. Once enabled, your DocuSign account must have a CLM production subscription and the credential must have been granted the OAuth scopes CLM needs; enabling a CLM resource type without them will fail the sync rather than silently sync no data, since ConductorOne doesn't validate the underlying subscription before letting you opt in. CLM permission sets sync for visibility only; DocuSign's CLM API has no endpoint to assign or unassign one.
 
 <Warning>
 If you use **OAuth Authentication** (the default, managed method), syncing CLM data requires ConductorOne's managed OAuth app to be granted the CLM API scopes on the platform side. If CLM data doesn't appear after setup, contact ConductorOne. This doesn't apply to **Custom App (Demo Environment)**, where the connector requests the CLM scopes directly using your own DocuSign app credentials.

docs/doc-info.md

@@ -45,7 +45,7 @@
 
    **Important Note about CLM:**
 
-   - CLM (Contract Lifecycle Management) is a separate, separately-licensed DocuSign product with its own API. There is no config flag to enable it: CLM resources sync whenever the account and credential can reach the CLM API, and accounts without CLM sync no CLM resources.
+   - CLM (Contract Lifecycle Management) is a separate, separately-licensed DocuSign product with its own API. The 5 CLM resource types carry `OptInRequired` and don't sync until a customer explicitly enables them in C1's sync configuration; C1's opt-in toggle doesn't validate the underlying subscription/scopes first, so an account that opts in but can't reach CLM fails the sync loudly rather than silently syncing zero CLM resources.
    - Requires a DocuSign CLM production subscription.
    - When using ConductorOne's managed OAuth app (the default cloud-hosted authentication method), CLM also requires that managed app to be granted the CLM API scope on ConductorOne's platform side — this is outside the connector's own configuration. Self-hosted or demo-environment setups using a customer-supplied DocuSign app do not have this extra requirement.
    - CLM permission sets sync for visibility only; DocuSign's CLM API has no endpoint to assign or unassign one, so they cannot be granted or revoked.
@@ -171,7 +171,7 @@ DocuSign CLM is a separate, separately-licensed DocuSign product. To sync CLM da
 
 1. Confirm your DocuSign account has a CLM production subscription.
 2. Confirm the credential has been granted the CLM OAuth scopes (`spring_read`/`spring_write`).
-3. The connector then syncs CLM Members, Roles, Groups, Folders, Folder Security, and Permission Sets automatically — there is no flag to set.
+3. The connector then syncs CLM Members, Roles, Groups, Folders, Folder Security, and Permission Sets once a customer explicitly enables each CLM resource type in C1's sync configuration (see the CLM note above — these types carry `OptInRequired`).
 
 If running against ConductorOne's managed OAuth app (the default cloud-hosted
 production authentication method), the managed app also needs the CLM API scopes

go.mod

@@ -11,6 +11,7 @@ require (
 	golang.org/x/oauth2 v0.36.0
 	google.golang.org/grpc v1.83.0
 	google.golang.org/protobuf v1.36.11
+	gopkg.in/yaml.v3 v3.0.1
 )
 
 require (
@@ -135,7 +136,6 @@ require (
 	google.golang.org/genproto/googleapis/api v0.0.0-20260526163538-3dc84a4a5aaa // indirect
 	google.golang.org/genproto/googleapis/rpc v0.0.0-20260729162451-8efbd57d26e0 // indirect
 	gopkg.in/yaml.v2 v2.4.0 // indirect
-	gopkg.in/yaml.v3 v3.0.1 // indirect
 	modernc.org/libc v1.72.0 // indirect
 	modernc.org/mathutil v1.7.1 // indirect
 	modernc.org/memory v1.11.0 // indirect

pkg/client/client.go

@@ -313,6 +313,16 @@ func (c *Client) ensureInitialized(ctx context.Context) error {
 	return nil
 }
 
+// EnsureReady exposes the base eSignature-credential check every other client method
+// runs internally before its real request, for callers with no eSignature endpoint of
+// their own that still need to detect whether the base connection/credentials are
+// valid — namely Connector.Validate() (see pkg/connector/connector.go), which runs
+// this once, up front, before any resource type's List() executes. Memoized after the
+// first successful call, same as every other method — see ensureInitialized.
+func (c *Client) EnsureReady(ctx context.Context) error {
+	return c.ensureInitialized(ctx)
+}
+
 // buildClientURL safely reads baseURI and accountId to build a URL.
 func (c *Client) buildClientURL(path string, params ...any) (*url.URL, error) {
 	c.mutex.RLock()

pkg/client/clm_client.go

@@ -208,12 +208,6 @@ func (c *Client) ensureClmInitialized(ctx context.Context) error {
 		for k := range raw {
 			keys = append(keys, k)
 		}
-		// codes.FailedPrecondition (not a bare error, which status.Code() would read as
-		// codes.Unknown): a non-CLM account's discovery response plausibly has a
-		// different shape entirely (e.g. a bare account object with none of the
-		// candidate fields), so isOptInFeatureUnavailableError needs a recognizable
-		// code to tolerate this specific failure the same way it tolerates 401/403 —
-		// see that function's doc in helper.go.
 		return status.Errorf(codes.FailedPrecondition, "baton-docusign: CLM account discovery response at %s did not contain a recognized "+
 			"base-URL field (checked %v); response contained these fields instead: %v", discoveryURL, clmBaseURLCandidateFields, keys)
 	}
@@ -223,6 +217,16 @@ func (c *Client) ensureClmInitialized(ctx context.Context) error {
 	return nil
 }
 
+// EnsureClmReady exposes the CLM-readiness check every other CLM client method runs
+// internally before its real request, for callers with no CLM endpoint of their own
+// that still need to detect CLM availability — namely Connector.Validate() (see
+// pkg/connector/connector.go), which runs this once, up front, before any CLM
+// builder's List() executes. Memoized after the first successful call, same as every
+// other CLM method — see ensureClmInitialized.
+func (c *Client) EnsureClmReady(ctx context.Context) error {
+	return c.ensureClmReady(ctx)
+}
+
 // clmExtractBaseURLField scans a CLM account discovery response for the first
 // recognized base-URL field, in clmBaseURLCandidateFields priority order. Split out
 // from ensureClmInitialized so this defensive-fallback logic can be unit tested

pkg/connector/clm_folders.go

@@ -18,6 +18,14 @@ import (
 
 var _ connectorbuilder.StaticEntitlementSyncerV2 = (*clmFolderBuilder)(nil)
 
+// The three folder-security principal kinds, as passed to logSkippedFolderSecurityEntry
+// and (via the principal_kind field) queryable in logs.
+const (
+	clmFolderPrincipalKindGroup = "group"
+	clmFolderPrincipalKindRole  = "role"
+	clmFolderPrincipalKindUser  = "user"
+)
+
 // The 5 grantable Baton entitlement slugs for CLM folder security, in ascending order
 // of access.
 const (
@@ -74,10 +82,6 @@ func (f *clmFolderBuilder) List(ctx context.Context, _ *v2.ResourceId, attr rs.S
 		PageToken: pageToken,
 	})
 	if err != nil {
-		if attr.PageToken.Token == "" && isOptInFeatureUnavailableError(err) {
-			ctxzap.Extract(ctx).Info("baton-docusign: CLM is not available for this account or token, skipping clm_folder sync", zap.Error(err))
-			return nil, &rs.SyncOpResults{}, nil
-		}
 		return nil, nil, err
 	}
 
@@ -141,6 +145,8 @@ func (f *clmFolderBuilder) Grants(ctx context.Context, folderResource *v2.Resour
 	for _, entry := range folder.Security.Groups {
 		slug, ok := clmSlugForAccessType(entry.AccessType)
 		if !ok {
+			logSkippedFolderSecurityEntry(ctx, clmFolderPrincipalKindGroup, entry.AccessType,
+				zap.String("folder_id", folderResource.Id.Resource), zap.String("group_href", entry.Href))
 			continue
 		}
 		principalID := &v2.ResourceId{ResourceType: clmGroupResourceType.Id, Resource: clmIDFromHref(entry.Href)}
@@ -156,12 +162,17 @@ func (f *clmFolderBuilder) Grants(ctx context.Context, folderResource *v2.Resour
 	for _, entry := range folder.Security.Roles {
 		slug, ok := clmSlugForAccessType(entry.AccessType)
 		if !ok {
+			logSkippedFolderSecurityEntry(ctx, clmFolderPrincipalKindRole, entry.AccessType,
+				zap.String("folder_id", folderResource.Id.Resource), zap.String("role", entry.Item))
 			continue
 		}
 		if !clmIsKnownRole(entry.Item) {
 			// clm_role is a fixed, hardcoded 5-role list (clmRoleBuilder.List) — a role
 			// name outside that set has no synced principal to grant against. Skip
 			// rather than emit a grant to a dangling/unsynced resource.
+			ctxzap.Extract(ctx).Debug("baton-docusign: skipping CLM folder role-security entry for an unrecognized role",
+				zap.String("folder_id", folderResource.Id.Resource), zap.String("role", entry.Item), zap.String("access_type", entry.AccessType),
+				zap.String("principal_kind", clmFolderPrincipalKindRole))
 			continue
 		}
 		principalID := &v2.ResourceId{ResourceType: clmRoleResourceType.Id, Resource: entry.Item}
@@ -171,6 +182,8 @@ func (f *clmFolderBuilder) Grants(ctx context.Context, folderResource *v2.Resour
 	for _, entry := range folder.Security.Users {
 		slug, ok := clmSlugForAccessType(entry.AccessType)
 		if !ok {
+			logSkippedFolderSecurityEntry(ctx, clmFolderPrincipalKindUser, entry.AccessType,
+				zap.String("folder_id", folderResource.Id.Resource), zap.String("member_href", entry.Href))
 			continue
 		}
 		principalID := &v2.ResourceId{ResourceType: clmMemberResourceType.Id, Resource: clmIDFromHref(entry.Href)}
@@ -180,6 +193,28 @@ func (f *clmFolderBuilder) Grants(ctx context.Context, folderResource *v2.Resour
 	return grants, &rs.SyncOpResults{Annotations: annos}, nil
 }
 
+// logSkippedFolderSecurityEntry Debug-logs an unmapped folder-security AccessType.
+// Benign values (NoAccess / Inherit) return without logging; Custom logs as an
+// unrepresentable active grant. kind is "group"|"role"|"user".
+func logSkippedFolderSecurityEntry(ctx context.Context, kind, accessType string, fields ...zap.Field) {
+	if clmIsBenignUnmappedAccessType(accessType) {
+		// The common steady-state case (NoAccess/InheritFromParentFolder, on every
+		// folder of every sync) — return before this function's own append/log call.
+		// The caller's fields are already built by this point regardless.
+		return
+	}
+	fields = append(fields, zap.String("principal_kind", kind), zap.String("access_type", accessType))
+	if accessType == client.ClmAccessTypeCustom {
+		ctxzap.Extract(ctx).Debug(
+			"baton-docusign: skipping CLM folder security entry with an unrepresentable Custom AccessType — a real, active grant C1 won't see",
+			fields...)
+		return
+	}
+	ctxzap.Extract(ctx).Debug(
+		"baton-docusign: skipping CLM folder security entry with an unmapped AccessType",
+		fields...)
+}
+
 // Grant sets a folder-security entry for the principal at the entitlement's tier.
 // Read-before-write: fetches the folder's current complete security state, modifies
 // only the one entry belonging to this principal (in whichever of Groups/Roles/Users
@@ -433,6 +468,17 @@ func clmSlugForAccessType(accessType string) (string, bool) {
 	return "", false
 }
 
+// clmIsBenignUnmappedAccessType is true for NoAccess and InheritFromParentFolder —
+// inert AccessTypes Grants() skips without logging. Custom is not benign.
+func clmIsBenignUnmappedAccessType(accessType string) bool {
+	switch accessType {
+	case client.ClmAccessTypeNoAccess, client.ClmAccessTypeInherit:
+		return true
+	default:
+		return false
+	}
+}
+
 // clmIsKnownRole reports whether name is one of the 5 fixed CLM account-level roles
 // (client.ClmRoles) — the same fixed set clmRoleBuilder.List syncs as clm_role
 // resources. Used to reject a folder-security Roles entry referencing a role outside