feat(controlplane): add workflow scope, attestation enforcement, and system flag to API tokens

Closes #3115

Extends the API token model with three internal capabilities:

- Workflow scope: tokens may optionally be scoped to a workflow within a
  project. The workflow is persisted on the apitoken row and embedded as
  workflow_id/workflow_name JWT claims. Expressed in biz via a new
  APITokenWithWorkflow(*Workflow) functional option, with validation that the
  workflow belongs to the requested project.

- Attestation enforcement: the auth middleware verifies the workflow_id JWT
  claim matches the row, and findWorkflowFromTokenOrNameOrRunID rejects when
  a workflow-scoped token operates on a different workflow. FindOrCreateWorkflow
  forbids workflow-scoped tokens from minting other workflows.

- System tokens: an immutable is_system flag on the row. System tokens mint
  and validate JWTs normally but are hidden from APITokenService/List by
  default and return NotFound on Revoke. Opt-in via WithIncludeSystemTokens()
  in biz; mint via APITokenAsSystem(). No public proto API change.

Signed-off-by: Miguel Martinez Trivino <miguel@chainloop.dev>

Author: migmartri

app/controlplane/internal/service/apitoken.go

@@ -160,6 +160,11 @@ func (s *APITokenService) Revoke(ctx context.Context, req *pb.APITokenServiceRev
 		return nil, handleUseCaseErr(err, s.log)
 	}
 
+	// System tokens are internal and must not be reachable through the public API.
+	if t.IsSystem {
+		return nil, errors.NotFound("not found", "API token not found")
+	}
+
 	// 1 - Only admins can manage global contracts
 	if t.ProjectID == nil && rbacEnabled(ctx) {
 		return nil, errors.BadRequest("invalid", "you can not manage a global API token")

app/controlplane/internal/service/attestation.go

@@ -710,22 +710,32 @@ func (s *AttestationService) findWorkflowFromTokenOrNameOrRunID(ctx context.Cont
 		return nil, biz.NewErrValidationStr("orgID must be provided")
 	}
 
-	// This is the case when the workflow if found by name
-	if workflowName != "" {
-		return s.workflowUseCase.FindByNameInOrg(ctx, orgID, projectName, workflowName)
-	}
-
-	// This is the case when the workflow is found by its reference to the run
-	if runID != "" {
+	var wf *biz.Workflow
+	switch {
+	case workflowName != "":
+		w, err := s.workflowUseCase.FindByNameInOrg(ctx, orgID, projectName, workflowName)
+		if err != nil {
+			return nil, err
+		}
+		wf = w
+	case runID != "":
 		run, err := s.wrUseCase.GetByIDInOrg(ctx, orgID, runID)
 		if err != nil {
 			return nil, fmt.Errorf("error retrieving the workflow run: %w", err)
 		}
+		wf = run.Workflow
+	default:
+		return nil, biz.NewErrValidationStr("workflowName or workflowRunId must be provided")
+	}
 
-		return run.Workflow, nil
+	// Workflow-scoped API tokens may only operate on their own workflow.
+	if apiToken := entities.CurrentAPIToken(ctx); apiToken != nil && apiToken.WorkflowID != nil {
+		if wf.ID != *apiToken.WorkflowID {
+			return nil, errors.Forbidden("forbidden", "API token is scoped to a different workflow")
+		}
 	}
 
-	return nil, biz.NewErrValidationStr("workflowName or workflowRunId must be provided")
+	return wf, nil
 }
 
 func checkAuthRequirements(attToken *usercontext.RobotAccount, workflowName string) error {
@@ -747,6 +757,11 @@ func (s *AttestationService) FindOrCreateWorkflow(ctx context.Context, req *cpAP
 		return nil, errors.NotFound("not found", "neither robot account nor API token found")
 	}
 
+	// Workflow-scoped API tokens cannot create or look up other workflows.
+	if token := entities.CurrentAPIToken(ctx); token != nil && token.WorkflowID != nil {
+		return nil, errors.Forbidden("forbidden", "API token is workflow-scoped and cannot create or look up other workflows")
+	}
+
 	// try to load project and apply RBAC if needed
 	if _, err := s.userHasPermissionOnProject(ctx, apiToken.OrgID, &cpAPI.IdentityReference{Name: &req.ProjectName}, authz.PolicyWorkflowCreate); err != nil {
 		// if the project is not found, check if user can create projects

app/controlplane/internal/usercontext/apitoken_middleware.go

@@ -80,10 +80,12 @@ func WithCurrentAPITokenAndOrgMiddleware(apiTokenUC *biz.APITokenUseCase, orgUC
 				// Project ID is optional
 				projectID, _ := genericClaims["project_id"].(string)
 
+				workflowID, _ := genericClaims["workflow_id"].(string)
+
 				// Scope is optional
 				scope, _ := genericClaims["scope"].(string)
 
-				ctx, err = setCurrentOrgAndAPIToken(ctx, apiTokenUC, orgUC, tokenID, projectID, scope)
+				ctx, err = setCurrentOrgAndAPIToken(ctx, apiTokenUC, orgUC, tokenID, projectID, workflowID, scope)
 				if err != nil {
 					return nil, fmt.Errorf("error setting current org and user: %w", err)
 				}
@@ -132,7 +134,7 @@ func WithAttestationContextFromAPIToken(apiTokenUC *biz.APITokenUseCase, orgUC *
 				return nil, fmt.Errorf("error extracting organization from APIToken: %w", err)
 			}
 
-			ctx, err = setCurrentOrgAndAPIToken(ctx, apiTokenUC, orgUC, tokenID, claims.ProjectID, claims.Scope)
+			ctx, err = setCurrentOrgAndAPIToken(ctx, apiTokenUC, orgUC, tokenID, claims.ProjectID, claims.WorkflowID, claims.Scope)
 			if err != nil {
 				return nil, fmt.Errorf("error setting current org and user: %w", err)
 			}
@@ -169,7 +171,7 @@ func setRobotAccountFromAPIToken(ctx context.Context, apiTokenUC *biz.APITokenUs
 }
 
 // Set the current organization and API-Token in the context
-func setCurrentOrgAndAPIToken(ctx context.Context, apiTokenUC *biz.APITokenUseCase, orgUC *biz.OrganizationUseCase, tokenID, projectIDInClaim, scope string) (context.Context, error) {
+func setCurrentOrgAndAPIToken(ctx context.Context, apiTokenUC *biz.APITokenUseCase, orgUC *biz.OrganizationUseCase, tokenID, projectIDInClaim, workflowIDInClaim, scope string) (context.Context, error) {
 	if tokenID == "" {
 		return nil, errors.New("error retrieving the key ID from the API token")
 	}
@@ -187,6 +189,13 @@ func setCurrentOrgAndAPIToken(ctx context.Context, apiTokenUC *biz.APITokenUseCa
 		return nil, errors.New("API token project mismatch")
 	}
 
+	// Same defense in depth for the workflow claim
+	if workflowIDInClaim != "" {
+		if token.WorkflowID == nil || token.WorkflowID.String() != workflowIDInClaim {
+			return nil, errors.New("API token workflow mismatch")
+		}
+	}
+
 	// Note: Expiration time does not need to be checked because that's done at the JWT
 	// verification layer, which happens before this middleware is called
 	if token.RevokedAt != nil {
@@ -224,14 +233,16 @@ func setCurrentOrgAndAPIToken(ctx context.Context, apiTokenUC *biz.APITokenUseCa
 	}
 
 	ctx = entities.WithCurrentAPIToken(ctx, &entities.APIToken{
-		ID:          token.ID.String(),
-		Name:        token.Name,
-		CreatedAt:   token.CreatedAt,
-		Token:       token.JWT,
-		ProjectID:   token.ProjectID,
-		ProjectName: token.ProjectName,
-		Policies:    token.Policies,
-		Scope:       scope,
+		ID:           token.ID.String(),
+		Name:         token.Name,
+		CreatedAt:    token.CreatedAt,
+		Token:        token.JWT,
+		ProjectID:    token.ProjectID,
+		ProjectName:  token.ProjectName,
+		WorkflowID:   token.WorkflowID,
+		WorkflowName: token.WorkflowName,
+		Policies:     token.Policies,
+		Scope:        scope,
 	})
 
 	// Set the authorization subject that will be used to check the policies

app/controlplane/internal/usercontext/apitoken_middleware_test.go

@@ -35,19 +35,27 @@ import (
 	"github.com/stretchr/testify/require"
 )
 
+type middlewareTestCase struct {
+	name          string
+	receivedToken bool
+	audience      string
+	tokenExists   bool
+	tokenRevoked  bool
+	orgExist      bool
+	// workflowIDClaim, if non-empty, is the workflow_id claim included on the JWT
+	workflowIDClaim string
+	// tokenWorkflowID, if set, is the workflow_id stored on the DB row
+	tokenWorkflowID *uuid.UUID
+	// the middleware logic got skipped
+	skipped bool
+	wantErr bool
+}
+
 func TestWithCurrentAPITokenAndOrgMiddleware(t *testing.T) {
 	logger := log.NewHelper(log.NewStdLogger(io.Discard))
-	testCases := []struct {
-		name          string
-		receivedToken bool
-		audience      string
-		tokenExists   bool
-		tokenRevoked  bool
-		orgExist      bool
-		// the middleware logic got skipped
-		skipped bool
-		wantErr bool
-	}{
+	matchingWorkflowID := uuid.New()
+	otherWorkflowID := uuid.New()
+	testCases := []middlewareTestCase{
 		{
 			name:          "invalid audience", // in this case it gets ignored
 			receivedToken: true,
@@ -90,6 +98,32 @@ func TestWithCurrentAPITokenAndOrgMiddleware(t *testing.T) {
 			audience:      apitoken.Audience,
 			wantErr:       true,
 		},
+		{
+			name:            "workflow claim matches DB row",
+			receivedToken:   true,
+			audience:        apitoken.Audience,
+			tokenExists:     true,
+			orgExist:        true,
+			workflowIDClaim: matchingWorkflowID.String(),
+			tokenWorkflowID: &matchingWorkflowID,
+		},
+		{
+			name:            "workflow claim does not match DB row",
+			receivedToken:   true,
+			audience:        apitoken.Audience,
+			tokenExists:     true,
+			workflowIDClaim: matchingWorkflowID.String(),
+			tokenWorkflowID: &otherWorkflowID,
+			wantErr:         true,
+		},
+		{
+			name:            "workflow claim present but DB row has none",
+			receivedToken:   true,
+			audience:        apitoken.Audience,
+			tokenExists:     true,
+			workflowIDClaim: matchingWorkflowID.String(),
+			wantErr:         true,
+		},
 	}
 
 	for _, tc := range testCases {
@@ -111,6 +145,9 @@ func TestWithCurrentAPITokenAndOrgMiddleware(t *testing.T) {
 					"aud": tc.audience,
 					"jti": wantToken.ID.String(),
 				}
+				if tc.workflowIDClaim != "" {
+					c["workflow_id"] = tc.workflowIDClaim
+				}
 
 				ctx = jwtmiddleware.NewContext(ctx, c)
 			}
@@ -119,6 +156,9 @@ func TestWithCurrentAPITokenAndOrgMiddleware(t *testing.T) {
 				if tc.tokenRevoked {
 					wantToken.RevokedAt = toTimePtr(time.Now())
 				}
+				if tc.tokenWorkflowID != nil {
+					wantToken.WorkflowID = tc.tokenWorkflowID
+				}
 
 				apiTokenRepo.On("FindByID", mock.Anything, wantToken.ID).Return(wantToken, nil)
 			} else if tc.receivedToken {

app/controlplane/internal/usercontext/entities/apitoken.go

@@ -1,5 +1,5 @@
 //
-// Copyright 2024-2025 The Chainloop Authors.
+// Copyright 2024-2026 The Chainloop Authors.
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.
@@ -26,11 +26,13 @@ import (
 type APIToken struct {
 	ID string
 	// Token Name
-	Name        string
-	CreatedAt   *time.Time
-	Token       string
-	ProjectID   *uuid.UUID
-	ProjectName *string
+	Name         string
+	CreatedAt    *time.Time
+	Token        string
+	ProjectID    *uuid.UUID
+	ProjectName  *string
+	WorkflowID   *uuid.UUID
+	WorkflowName *string
 	// ACL policies for this token. Used for authorization checks.
 	Policies []*authz.Policy
 	Scope    string

app/controlplane/pkg/biz/apitoken.go

@@ -65,12 +65,17 @@ type APIToken struct {
 	// If the token is scoped to a project
 	ProjectID   *uuid.UUID
 	ProjectName *string
+	// If the token is scoped to a specific workflow within a project
+	WorkflowID   *uuid.UUID
+	WorkflowName *string
 	// ACL policies for this token
 	Policies []*authz.Policy
+	// IsSystem marks tokens minted by internal code paths; these are hidden from the public API.
+	IsSystem bool
 }
 
 type APITokenRepo interface {
-	Create(ctx context.Context, name string, description *string, expiresAt *time.Time, organizationID *uuid.UUID, projectID *uuid.UUID, policies []*authz.Policy) (*APIToken, error)
+	Create(ctx context.Context, name string, description *string, expiresAt *time.Time, organizationID *uuid.UUID, projectID *uuid.UUID, workflowID *uuid.UUID, policies []*authz.Policy, isSystem bool) (*APIToken, error)
 	List(ctx context.Context, orgID *uuid.UUID, filters *APITokenListFilters) ([]*APIToken, error)
 	Revoke(ctx context.Context, orgID *uuid.UUID, ID uuid.UUID) error
 	// FindInactive returns tokens in an organization that have been inactive since the given cutoff time.
@@ -143,9 +148,10 @@ func NewAPITokenUseCase(apiTokenRepo APITokenRepo, jwtConfig *APITokenJWTConfig,
 }
 
 type apiTokenOptions struct {
-	project              *Project
-	showOnlySystemTokens bool
-	policies             []*authz.Policy
+	project  *Project
+	workflow *Workflow
+	policies []*authz.Policy
+	isSystem bool
 }
 
 type APITokenCreateOpt func(*apiTokenOptions)
@@ -156,12 +162,28 @@ func APITokenWithProject(project *Project) APITokenCreateOpt {
 	}
 }
 
+// APITokenWithWorkflow scopes the token to a specific workflow within a project.
+// Must be combined with APITokenWithProject; the workflow's project must match.
+func APITokenWithWorkflow(workflow *Workflow) APITokenCreateOpt {
+	return func(o *apiTokenOptions) {
+		o.workflow = workflow
+	}
+}
+
 func APITokenWithPolicies(policies []*authz.Policy) APITokenCreateOpt {
 	return func(o *apiTokenOptions) {
 		o.policies = policies
 	}
 }
 
+// APITokenAsSystem marks the token as system-managed (internal). System tokens
+// are hidden from the public API.
+func APITokenAsSystem() APITokenCreateOpt {
+	return func(o *apiTokenOptions) {
+		o.isSystem = true
+	}
+}
+
 // expires in is a string that can be parsed by time.ParseDuration
 func (uc *APITokenUseCase) Create(ctx context.Context, name string, description *string, expiresIn *time.Duration, orgID *string, opts ...APITokenCreateOpt) (*APIToken, error) {
 	ctx, span := otelx.Start(ctx, apiTokenTracer, "APITokenUseCase.Create")
@@ -212,6 +234,17 @@ func (uc *APITokenUseCase) Create(ctx context.Context, name string, description
 		projectID = ToPtr(options.project.ID)
 	}
 
+	var workflowID *uuid.UUID
+	if options.workflow != nil {
+		if options.project == nil {
+			return nil, NewErrValidationStr("workflow scope requires a project scope")
+		}
+		if options.workflow.ProjectID != options.project.ID {
+			return nil, NewErrValidationStr("workflow does not belong to the requested project")
+		}
+		workflowID = ToPtr(options.workflow.ID)
+	}
+
 	// Use provided policies if present, otherwise use defaults
 	policies := options.policies
 	if policies == nil {
@@ -225,7 +258,7 @@ func (uc *APITokenUseCase) Create(ctx context.Context, name string, description
 
 	// NOTE: the expiration time is stored just for reference, it's also encoded in the JWT
 	// We store it since Chainloop will not have access to the JWT to check the expiration once created
-	token, err := uc.apiTokenRepo.Create(ctx, name, description, expiresAt, orgUUID, projectID, policies)
+	token, err := uc.apiTokenRepo.Create(ctx, name, description, expiresAt, orgUUID, projectID, workflowID, policies, options.isSystem)
 	if err != nil {
 		if IsErrAlreadyExists(err) {
 			return nil, NewErrAlreadyExistsStr("name already taken")
@@ -252,6 +285,11 @@ func (uc *APITokenUseCase) Create(ctx context.Context, name string, description
 		generationOpts.ProjectName = ToPtr(options.project.Name)
 	}
 
+	if options.workflow != nil {
+		generationOpts.WorkflowID = ToPtr(options.workflow.ID)
+		generationOpts.WorkflowName = ToPtr(options.workflow.Name)
+	}
+
 	// generate the JWT
 	token.JWT, err = uc.jwtBuilder.GenerateJWT(generationOpts)
 	if err != nil {
@@ -341,6 +379,14 @@ func WithAPITokenScope(scope APITokenScope) APITokenListOpt {
 	}
 }
 
+// WithIncludeSystemTokens opts the listing in to also return system-managed tokens.
+// By default, system tokens are hidden.
+func WithIncludeSystemTokens() APITokenListOpt {
+	return func(opts *APITokenListFilters) {
+		opts.IncludeSystem = true
+	}
+}
+
 type APITokenScope string
 
 const (
@@ -376,6 +422,9 @@ type APITokenListFilters struct {
 	StatusFilter APITokenStatusFilter
 	// FilterByScope is used to filter the result by the scope of the token
 	FilterByScope APITokenScope
+	// IncludeSystem controls whether system-managed tokens are returned.
+	// Defaults to false (system tokens are hidden).
+	IncludeSystem bool
 }
 
 func (uc *APITokenUseCase) List(ctx context.Context, orgID string, opts ...APITokenListOpt) ([]*APIToken, error) {